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:
`sort[object of sort]=<property name>`
E.g.
`sort[standards]=number.enhanced`
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.
`sort[standards]=number.enhanced,statement.descr`
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:
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). If you sort on custom attributes of different types, ascending sorts put number attribute values above text attribute values. Descending sorts reverse the order. Note that within a given type, numbers are sorted numerically and text attributes are sorted alphabetically.
Introduction
Explore services, tools, and guides to build seamless integrations in the Instructure ecosystem.
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
Call Throttling
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 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 . 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
Addressing Object Properties
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
`sort[standards]=-number.enhanced`
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.
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 .
Get Started
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!
Take your authentication key or secret you got in the previous step.
Find an API you would like to try.
If there is a "Test it" button, you can click on it and test it on the spot.
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.
Services
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.
Elevate Standards Alignment - AB Connect
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.
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 .
Pagination
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Pagination
Requests that return multiple items will be paginated to 10 items by default. You can set a custom per-page amount with the
API Token Scopes
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
API Token Scopes API
Masquerading
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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.
API Endpoint Attributes
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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:
Providers
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.
Accounts (LTI)
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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.
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 headers should be used. These links should be treated as opaque. They will be absolute urls that include all parameters necessary to retrieve the desired current, next, previous, first, or last page. The one exception is that if an access_token parameter is sent for authentication, it will not be included in the returned links, and must be re-appended.
Pagination information is provided in the Link header:
The possible rel values are:
current - link to the current page of results.
next - link to the next page of results.
prev - link to the previous page of results.
first - link to the first page of results.
last - link to the last page of results.
These will only be included if they are relevant. For example, the first page of results will not contain a rel="prev" link. rel="last" may also be excluded if the total count is too expensive to compute on each request.
NOTE: Because HTTP header names are case-insensitive, please be sure you are not parsing the Link header in a case-sensitive way. The capitalization of the header name is not guaranteed.
This documentation is generated directly from the Canvas LMS source code, available on Github.
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):
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 on Github.
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
File
Folder
Quiz
Module
SessionlessLaunchUrl
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 on Github.
{
// 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"
}
<a href="http://canvas.example.com/courses/123/pages/a-wiki-page"
data-api-endpoint="http://canvas.example.com/api/v1/courses/123/pages/a-wiki-page"
data-api-returntype="Page">More information here</a>
{
// the ID of the Account object
"id": 2,
// The display name of the account
"name": "Canvas Account",
// The UUID of the account
"uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5",
// The account's parent ID, or null if this is the root account
"parent_account_id": 1,
// The ID of the root account, or null if this is the root account
"root_account_id": 1,
// The state of the account. Can be 'active' or 'deleted'.
"workflow_state": "active"
}
Single Provider
In its simplest form, you are able to retrieve the details of a specific Provider by appending the AB GUID to the path portion of the URL.
Fetching a Provider
Searching for Providers
Using filtering and facets, it is possible to retrieve sets of Providers that match specific criteria. These Providers are returned in an array of Provider objects. See the Introduction for an explanation on filtering and the use of facets. This section covers the specifics of using these parameters with the Providers resource. Note that by default, the endpoint returns your Provider object and the objects of all Providers related to you.
Create a new Developer Key Account Binding. The developer key specified in the request URL must be available in the requested account or the requested account’s account chain. If the binding already exists for the specified account/key combination it will be updated.
Request Parameters:
Parameter
Type
Description
Returns a object.
This documentation is generated directly from the Canvas LMS source code, available .
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 .
Canvas LMS
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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.
SIS IDs
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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
Paging Data
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.
Throttling
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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
Brand Configs
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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 on Github.
. 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
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)
lti_1_3_id (for users, a separate value from lti_context_id, sent in LTI 1.3 launches as sub)
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 to mean the default term, and current to mean the term that is currently active according to term dates. A term must have a start date or an end date to be considered the current term. If there is more than one term that's active, current will not be found.
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:
Also beware that if you use ProxyPass, you should enable the nocanon option. Similarly, RewriteRule should use the NE, 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 on Github.
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 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.
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 on Github.
[
{
"name": "University of Utah",
"domain": "utah.edu",
"distance": null, // distance is always nil, but preserved in the api response for backwards compatibility
"authentication_provider": "canvas", // which authentication_provider param to pass to the oauth flow; may be NULL
},
...
]
{
// The ID of the Assignment the extension belongs to.
"assignment_id": 2,
// The ID of the Student that needs the assignment extension.
"user_id": 3,
// Number of times the student is allowed to re-submit the assignment
"extra_attempts": 2
}
{
// The Canvas ID of the binding
"id": 1,
// The global Canvas ID of the account in the binding
"account_id": 10000000000001,
// The global Canvas ID of the developer key in the binding
"developer_key_id": 10000000000008,
// The workflow state of the binding. Will be one of 'on', 'off', or 'allow.'
"workflow_state": on,
// True if the requested context owns the binding
"account_owns_binding": true
}
All integer ids in Canvas are 64 bit integers. String ids are also used in Canvas.
To force all ids to strings add the request header Accept: application/json+canvas-string-ids This will cause Canvas to return even integer IDs as strings, preventing problems with languages (particularly JavaScript) that can't properly process large integers.
All boolean parameters can be passed as true/false, t/f, yes/no, y/n, on/off, or 1/0. When using JSON format, a literal true/false is preferred, rather than as a string.
For POST and PUT requests, parameters are sent using standard HTML form encoding (the application/x-www-form-urlencoded content type).
POST and PUT requests may also optionally be sent in JSON format format. The content-type of the request must be set to application/json in this case. There is currently no way to upload a file as part of a JSON POST, the multipart form type must be used.
As an example, this HTML form request:
would translate into this JSON request:
With either encoding, all timestamps are sent and returned in ISO 8601 format (UTC time zone):
Authentication
API authentication is done with OAuth2. If possible, using the HTTP Authorization header is recommended. Sending the access token in the query string or POST parameters is also supported.
Note that if you make an API call using HTTP instead of HTTPS, you will be redirected to HTTPS. However, at that point, the credentials have already been sent in clear over the internet. Please make sure that you are using HTTPS.
Canvas Experiences
Canvas LMS supports several experiences including Canvas Career and Canvas for Elementary. The vast majority of these API resources are shared, though some are applicable only to certain experiences.
About this Documentation
This documentation is generated directly from the Canvas LMS code. You can generate this documentation yourself if you've set up a local Canvas environment following the instructions on Github. Run the following command from your Canvas directory:
OpenAPI 3.0 Specification
Canvas also provides an OpenAPI 3.0 specification that can be generated from the same YARD documentation. This modern format is compatible with tools like Swagger UI, Postman, and various code generators.
To generate the OpenAPI 3.0 specification:
This will create public/doc/openapi/canvas.openapi.yaml containing the OpenAPI 3.0 specification for the Canvas API.
The OpenAPI spec includes:
All API endpoints with their HTTP methods and paths
Request parameters (path, query, and body)
Response schemas
Authentication requirements
Server configuration
You can view and interact with the generated OpenAPI spec using:
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
Parameter
Type
Description
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 .
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.
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 .
Events
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.
API for managing user career experience and role preferences in Canvas.
An ExperienceSummary object looks like:
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:
Parameter
Type
Description
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:
Parameter
Type
Description
Example Request:
This documentation is generated directly from the Canvas LMS source code, available .
Admins
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Admins API
Manage account role assignments
Authentications Log
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Authentications Log API
Query audit log of authentication events (logins and logouts).
CommMessages
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
CommMessages API
API for accessing the messages (emails, sms, etc) that have been sent to a user.
BlockEditorTemplate
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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.
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.
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.
{
node(id: "Q291cnNlLTE=") {
... on Course {
_id # traditional ids (e.g. "1")
name
term { name }
}
}
}
{
# object type must be specified when using legacyNode
legacyNode(type: Course, _id: "1") {
... on Course {
_id
name
}
}
}
{
# NOTE: id arguments will always take either GraphQL or rest-style ids
c1: course(id: "1") {
_id
name
}
c2: course(id: "Q291cnNlLTE=") {
_id
name
}
}
{
course(id: "1") {
assignmentsConnection(
first: 10, # page size
after: "XYZ" # `endCursor` from previous page
) {
nodes {
id
name
}
pageInfo {
endCursor # this is your `after` value for the next request
hasNextPage
}
}
}
}
{
assignment(id: "1") {
submissionsConnection(first: 10) {
nodes {
id
state
}
pageInfo {
hasNextPage
totalCount # total number of submissions (ignoring pagination)
}
}
}
}
url:<HTTP Verb>|<Canvas API Endpoint Path>
url:GET|/api/v1/courses/:course_id/rubrics
{
// 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"]
}
{
// timestamp of the event
"created_at": "2012-07-19T15:00:00-06:00",
// authentication event type ('login' or 'logout')
"event_type": "login",
// ID of the pseudonym (login) associated with the event
"pseudonym_id": 9478,
// ID of the account associated with the event. will match the account_id in the
// associated pseudonym.
"account_id": 2319,
// ID of the user associated with the event will match the user_id in the
// associated pseudonym.
"user_id": 362
}
Event is somewhere later in the queue. For example:
You are licensed to Standard A.
You sync up all changes.
Standard A changes so an Event is created and you have access to it.
You remove Standard A from your delivery.
You sync up changes.
You get a change Event for Standard A but you no longer have access to it.
A paginated list of the current user’s roles in the account. The results are the same as those returned by the List account admins endpoint with user_id set to self, except the “Admins - Add / Remove” permission is not required.
Whether the current CSP settings are inherited from a parent account.
settings_locked
Whether current CSP settings can be overridden by sub-accounts and courses.
effective_whitelist
If enabled, lists the currently allowed domains (includes domains automatically allowed through external tools).
tools_whitelist
(Account-only) Lists the automatically allowed domains with their respective external tools
current_account_whitelist
(Account-only) Lists the current list of domains explicitly allowed by this account. (Note: this list will not take effect unless CSP is explicitly enabled on this account)
BETA: This API endpoint is not finalized, and there could be breaking changes before its final release.
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, PublishedEventData, UnpublishedEventData, DeletedEventData, RestoredEventData, ResetFromEventData, ResetToEventData, CopiedFromEventData, and CopiedToEventData objects will return a empty objects as these do not have any additional log data associated.
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:
Parameter
Type
Description
Example Request:
Returns a list of objects.
GET /api/v1/courses/:course_id/potential_collaborators
API for retrieving announcements. This API is Announcement-specific. See also the Discussion Topics API, which operates on Announcements also.
GET /api/v1/announcements
Scope:url:GET|/api/v1/announcements
Returns the paginated list of announcements for the given courses and date range. Note that a context_code field is added to the responses so you can tell which course each announcement belongs to.
Request Parameters:
Parameter
Type
Description
Example Request:
Example Response:
Returns a list of objects.
This documentation is generated directly from the Canvas LMS source code, available .
Asset Definitions
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
Assessment Question Banks
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Assessment Question Banks API
An AssessmentQuestionBank object looks like:
AI Experiences
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
AI Experiences API
API for creating, accessing and updating AI Experiences. AI Experiences are used to create interactive AI-powered learning scenarios within courses.
Access Tokens
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Access Tokens API
A Token object looks like:
Communication Channels
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Communication Channels API
API for accessing users' email and SMS communication channels.
Announcement External Feeds
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
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.
Bookmarks
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Bookmarks API
A Bookmark object looks like:
Error Reports
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Error Reports API
An ErrorReport object looks like:
ePub Exports
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
ePub Exports API
API for exporting courses as an ePub
Character Set Support
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.
Standards
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
Topics
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
{
// The unique identifier for the account role/user assignment.
"id": 1023,
// The account role assigned. This can be 'AccountAdmin' or a user-defined role
// created by the Roles API.
"role": "AccountAdmin",
// The user the role is assigned to. See the Users API for details.
"user": null,
// The status of the account role/user assignment.
"workflow_state": "deleted"
}
{
// The ID of the CommMessage.
"id": 42,
// The date and time this message was created
"created_at": "2013-03-19T21:00:00Z",
// The date and time this message was sent
"sent_at": "2013-03-20T22:42:00Z",
// The workflow state of the message. Possible values: 'created' : The message
// has been created, but not yet processed. 'staged' : The message is queued for
// sending. 'sending' : The message is being sent currently. 'sent' : The
// message has been successfully sent. 'bounced' : An error occurred during the
// sending of the message.'dashboard' : The message has been sent to the
// dashboard. 'closed' : The message has been sent and closed, typically for
// dashboard messages or messages sent to deleted users. 'cancelled' : The
// message was cancelled before it could be sent.
"workflow_state": "sent",
// The address that was put in the 'from' field of the message
"from": "[email protected]",
// The display name for the from address
"from_name": "Instructure Canvas",
// The address the message was sent to:
"to": "[email protected]",
// The reply_to header of the message
"reply_to": "[email protected]",
// The message subject
"subject": "example subject line",
// The plain text body of the message
"body": "This is the body of the message",
// The HTML body of the message.
"html_body": "<html><body>This is the body of the message</body></html>"
}
{
// 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"
}
When set to true, returns admins who have been deleted
role_id
integer
The user’s admin relationship with the account will be created with the given role. Defaults to the built-in role for ‘AccountAdmin’.
send_confirmation
boolean
Send a notification email to the new admin if true. Default is true.
end_time
DateTime
The end of the time range you want to retrieve messages for. Up to a year prior to the current date is available.
drafts
boolean
If true, include draft templates. If false or omitted only published templates will be returned.
type[]
string
What type of templates should be returned.
Allowed values: page, section, block
include[]
string
no description
Allowed values: node_tree, thumbnail
status
Required string
If set to “enabled” for an account, CSP will be enabled for all its courses and sub-accounts (that have not explicitly enabled or disabled it), using the allowed domains set on this account. If set to “disabled”, CSP will be disabled for this account or course and for all sub-accounts that have not explicitly re-enabled it. If set to “inherited”, this account or course will reset to the default state where CSP settings are inherited from the first parent account to have them explicitly set.
Allowed values: enabled, disabled, inherited
settings_locked
Required boolean
Whether sub-accounts and courses will be prevented from overriding settings inherited from this account.
The number of extra minutes to allow for all attempts. This will add to the existing time limit on the submission. This is limited to 10080 minutes (1 week)
manually_unlocked
boolean
Allow the student to take the quiz even if it’s locked for everyone else.
extend_from_now
integer
The number of minutes to extend the quiz from the current time. This is mutually exclusive to extend_from_end_at. This is limited to 1440 minutes (24 hours)
extend_from_end_at
integer
The number of minutes to extend the quiz beyond the quiz’s current ending time. This is mutually exclusive to extend_from_now. This is limited to 1440 minutes (24 hours)
user_id
Required integer
The ID of the user we want to add quiz extensions for.
extra_attempts
integer
Number of times the student is allowed to re-take the quiz over the multiple-attempt limit. This is limited to 1000 attempts or less.
If set to “live”, returns only conferences that are live (i.e., have started and not finished yet). If omitted, returns all conferences for this user’s groups and courses.
The parameters will vary for each report. A few example parameters have been provided below. Note: the example parameters provided below may not be valid for every report.
parameters[section_ids[]]
integer
The sections of the course to report on. Note: this parameter has been listed to serve as an example and may not be valid for every report.
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.
{
// ID of the course for the event.
"course": 12345,
// ID of the user for the event (who made the change).
"user": 12345,
// ID of the page view during the event if it exists.
"page_view": "e2b76430-27a5-0131-3ca1-48e0eb13f29b",
// ID of the course that this course was copied from. This is only included if
// the event_type is copied_from.
"copied_from": 12345,
// ID of the course that this course was copied to. This is only included if the
// event_type is copied_to.
"copied_to": 12345,
// ID of the SIS batch that triggered the event.
"sis_batch": 12345
}
{
// ID of the event.
"id": "e2b76430-27a5-0131-3ca1-48e0eb13f29b",
// timestamp of the event
"created_at": "2012-07-19T15:00:00-06:00",
// Course event type The event type defines the type and schema of the
// event_data object.
"event_type": "updated",
// Course event data depending on the event type. This will return an object
// containing the relevant event data. An updated event type will return an
// UpdatedEventData object.
"event_data": "{}",
// Course event source depending on the event type. This will return a string
// containing the source of the event.
"event_source": "manual|sis|api",
// Jsonapi.org links
"links": {"course":"12345","user":"12345","page_view":"e2b76430-27a5-0131-3ca1-48e0eb13f29b"}
}
// The created event data object returns all the fields that were set in the
// format of the following example. If a field does not exist it was not set.
// The value of each field changed is in the format of [:old_value, :new_value].
// The created event type also includes a created_source field to specify what
// triggered the creation of the course.
{
"name": [null, "Course 1"],
"start_at": [null, "2012-01-19T15:00:00-06:00"],
"conclude_at": [null, "2012-01-19T15:00:00-08:00"],
"is_public": [null, false],
// The type of action that triggered the creation of the course.
"created_source": "manual|sis|api"
}
// The updated event data object returns all the fields that have changed in the
// format of the following example. If a field does not exist it was not
// changed. The value is an array that contains the before and after values for
// the change as in [:old_value, :new_value].
{
"name": ["Course 1", "Course 2"],
"start_at": ["2012-01-19T15:00:00-06:00", "2012-07-19T15:00:00-06:00"],
"conclude_at": ["2012-01-19T15:00:00-08:00", "2012-07-19T15:00:00-08:00"],
"is_public": [true, false]
}
{
// 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"
}
{
// 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
}
{
// 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
}
// The parameters returned will vary for each report.
{
}
{
// 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"
}
{
// 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"
}
// Combination of a Course & EpubExport.
{
// the unique identifier for the course
"id": 101,
// the name for the course
"name": "Maths 101",
// ePub export API object
"epub_export": null
}
{
// the unique identifier for the export
"id": 101,
// the date and time this export was requested
"created_at": "2014-01-01T00:00:00Z",
// attachment api object for the export ePub (not present until the export
// completes)
"attachment": {"url":"https:\/\/example.com\/api\/v1\/attachments\/789?download_frd=1"},
// The api endpoint for polling the current progress
"progress_url": "https://example.com/api/v1/progress/4",
// The ID of the user who started the export
"user_id": 4,
// Current state of the ePub export: created exporting exported generating
// generated failed
"workflow_state": "exported"
}
`Content-Type: application/json; charset=utf-8`
Hash
The select parameter allows exporting specific data. The keys are object types like ‘files’, ‘folders’, ‘pages’, etc. The value for each key is a list of object ids. An id can be an integer or a string.
Multiple object types can be selected in the same call. However, not all object types are valid for every export_type. Common Cartridge supports all object types. Zip and QTI only support the object types as described below.
“folders”
Also supported for zip export_type.
export_type
Required string
“common_cartridge”
Export the contents of the course in the Common Cartridge (.imscc) format
“qti”
Export quizzes from a course in the QTI format
“zip”
Export files from a course, group, or user in a zip file
Allowed values: common_cartridge, qti, zip
skip_notifications
boolean
Don’t send the notifications about the export to the user. Default: false
Only return announcements posted before the end_date (inclusive). Defaults to 28 days from start_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. Announcements scheduled for future posting will only be returned to course administrators.
available_after
Date
Only return announcements having locked_at nil or after available_after (exclusive). The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. Effective only for students (who don’t have moderate forum right).
active_only
boolean
Only return active announcements that have been published. Applies only to requesting users that have permission to view unpublished items. Defaults to false for users with access to view unpublished items, otherwise true and unmodifiable.
latest_only
boolean
Only return the latest announcement for each associated context. The response will include at most one announcement for each specified context in the context_codes[] parameter. Defaults to false.
include
array
Optional list of resources to include with the response. May include a string of the name of the resource. Possible values are: “sections”, “sections_user_count” if “sections” is passed, includes the course sections that are associated with the topic, if the topic is specific to certain sections of the course. If “sections_user_count” is passed, then:
context_codes[]
Required string
List of context_codes to retrieve announcements for (for example, course_123). Only courses are presently supported. The call will fail unless the caller has View Announcements permission in all listed courses.
start_date
Date
Only return announcements posted since the start_date (inclusive). Defaults to 14 days ago. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
Returns a list of manually generated access tokens for the specified user. Note that the actual token values are only returned when the token is first created.
Request Parameters:
Parameter
Type
Description
per_page
integer
The number of results to return per page. Defaults to 10. Maximum of 100.
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.
Creates a new communication channel for the specified user.
Request Parameters:
Parameter
Type
Description
communication_channel[address]
Required string
An email address or SMS number. Not required for “push” type channels.
communication_channel[type]
Required string
The type of communication channel.
In order to enable push notification support, the server must be properly configured (via sns_creds in Vault) to communicate with Amazon Simple Notification Services, and the developer key used to create the access token from this request must have an SNS ARN configured on it.
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 filtering and the use of facets. This section covers the specifics of using these parameters with the Standards resource.
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 AB Support 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 filtering and the use of facets. This section covers the specifics of using these parameters with the Topics resource.
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[asset_definitions]stringOptional
comma separated list of field names
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestring · enumOptional
Literal "asset_definitions" - JSON API requirement.
Possible values:
typestringOptional
Literal "asset_definitions" - JSON API requirement.
asset_typestringOptional
The Asset Definition name.
filterablestringOptional
The flag to determine if this property is filterable or not.
seqnumberOptional
The position of this property in this asset type.
labelstringOptional
The actual name of this property.
idstringOptional
API identifier for the field which uniquely identifies the entity to be filtered by. This is the property you would use when constructing your filters statement.
namestringOptional
The API-recognized name for the entity you are using to filter. This is the property you would use when asking for facets.
idstringOptional
The API Identifier for the entity-unique property in the facets response. This is the property you would use when constructing your filter statement and thus must correspond with the values in this entity’s field.id.
namestringOptional
The API Identifier for the human-readable property in the facets response.
guidstringOptional
Unique identifier of the object.
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[asset_definitions]stringOptional
comma separated list of field names
filter[asset_definitions]stringOptional
an ODATA-like query string used to filter
sort[asset_definitions]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
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.
Group
Operation
Description
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')
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
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.
There are two ways to upload a file to Canvas: either by sending the file data in a POST request, or by sending Canvas a publicly accessible HTTP or HTTPS URL to the file.
There are three steps to uploading a file directly via POST:
Notify Canvas that you are uploading a file with a POST to the file creation endpoint. This POST will include the file name and file size, along with information about what context the file is being created in.
Upload the file using the information returned in the first POST request.
On successful upload, the API will respond with a redirect. This redirect needs to be followed to complete the upload, or the file may not appear.
Step 1: Telling Canvas about the file upload and getting a token
The first step is to POST to the relevant API endpoint, depending on where you want to create the file. For example, to , you'd POST to /api/v1/courses/:course_id/files. Or to , as the student you'd POST to /api/v1/courses/:course_id/assignments/:assignment_id/submissions/self/files or /api/v1/courses/:course_id/assignments/:assignment_id/submissions/comments/self/files for submission comments.
Note* The endpoint you choose to post files to will change the permissions set on the file. i.e. only files posted to the submissions comments endpoint can be attached to a submissions comment.
Arguments:
name
The filename of the file. Any UTF-8 name is allowed. Path components such as `/` and `\` will be treated as part of the filename, not a path to a sub-folder.
size
The size of the file, in bytes. This field is recommended, as it will let you find out if there's a quota issue before uploading the raw file.
Example Request:
Example Response:
At this point, the file object has been created in Canvas in a "pending" state, with no content. It will not appear in any listings in the UI until the next two steps are completed. The returned Signature is valid for 30 minutes.
Step 2: Upload the file data to the URL given in the previous response
Using the data in the JSON response from Step 1, the application can now upload the actual file data, by POSTing a specially formulated request to the URL given in the upload_url field of the response.
Depending on how Canvas is configured, this upload URL might be another URL in the same domain, or a Amazon S3 bucket, or some other URL. In order to work with all Canvas installations, applications should be very careful to follow this documentation and not make any undocumented assumptions about the upload workflow.
This second request must be POSTed as a multipart/form-data request to accomodate the file data. The parameters POSTed with this request come directly from the upload_params part of the JSON response in Step 1.
The only addition is the file parameter which must be posted as the last parameter following all the others.
Example Request:
The access token is not sent with this request.
Example Response:
IMPORTANT: The request is signed, and will be denied if any parameters from the upload_params response are added, removed or modified. The parameters in upload_params may vary over time, and between Canvas installs. It's important for the application to copy over all of the parameters, and not rely on the names or values of the params for any functionality.
This example assumes there is a file called my_local_file.jpg in the current directory.
Step 3: Confirm the upload's success
If Step 2 is successful, the response will be either a 3XX redirect or 201 Created with a Location header set as normal.
In the case of a 3XX redirect, the application needs to perform a GET to this location in order to complete the upload, otherwise the new file may not be marked as available. (Note: While a POST would be truer to REST semantics, a GET is required for forwards compatibility with the 201 Created response described below.) This request is back against Canvas again, and needs to be authenticated using the normal API access token authentication.
In the case of a 201 Created, the upload has been complete and the Canvas JSON representation of the file can be retrieved with a GET from the provided Location.
Example Request:
Example Response:
Instead of uploading a file directly, you can also provide Canvas a public HTTP or HTTPS URL from which to retrieve the file.
Step 1a: Posting the file URL to Canvas
The first step is the same as with the "Uploading via POST" flow above, with the addition of a few new parameters:
url
The full URL to the file to be uploaded. This URL must be publicly accessible.
submit_assignment
A boolean to indicate whether or not to automatically submit the assignment the file is associated with if it is associated with an assignment. Defaults to true.
Example Request:
Example Response:
Step 1b: Understanding the response
Canvas' file management is in a moment of transition. For the duration of this transition, there are two possible behaviors. The newer behavior includes additional fields in the response to the first request and expects an additional action from the application.
In the deprecated behavior, Canvas will initiate a "cloning" of the provided URL by downloading it via Canvas servers. The initial POST was sufficient to start this and no other action is necessary from the application.
In the newer behavior, Canvas delegates the cloning of the URL to the same service that accepts direct uploads. The cloning is kicked off by a POST by the application to the provided upload_url with the provided upload_params, in parallel with a direct upload. The service then informs Canvas directly when it is complete.
In either case, the cloning of the URL will be performed in the background, and the file will not necessarily be immediately available when the API calls complete. Instead, a progress object is provided which can be periodically polled to check the status of the upload.
You can distinguish the new behavior (and expected follow up) from the old behavior precisely by the presence or absence of the upload_url key.
Step 2: POST to the URL given in the previous response
If the response to the initial POST includes an upload_url, you must POST to it with the upload_params just as if you were performing a direct upload. The only exception is that the file parameter is omitted. The Content-Type is still expected to be multipart/form-data.
Example Request:
Example Response:
This step is not necessary with the old behavior.
Step 3: Check to see when the upload is complete
If the application needs to know the outcome of the upload, it can use the {api:ProgressController#Show Progress endpoint} to query the status. On success, the created attachment's id will be returned in the results of the Progress object as id.
This documentation is generated directly from the Canvas LMS source code, available .
API for viewing and toggling settings of account calendars.
An account calendar is available for each account in Canvas. All account calendars are hidden by default, but administrators with the manage_account_calendar_visibility permission may set calendars as visible. Administrators with the manage_account_calendar_events permission can create events in visible account calendars, and users associated with an account can add the calendar and see its events (if the calendar is visible). Events on calendars set as auto_subscribe calendars will appear on users' calendars even if they do not manually add it.
An AccountCalendar object looks like:
GET /api/v1/account_calendars
Scope:url:GET|/api/v1/account_calendars
Returns a paginated list of account calendars available to the current user. Includes visible account calendars where the user has an account association.
Set visibility and/or auto_subscribe on many calendars simultaneously. Requires the manage_account_calendar_visibility permission on the account.
Accepts a JSON array of objects containing 2-3 keys each: id (the account’s id, required), visible (a boolean indicating whether the account calendar is visible), and auto_subscribe (a boolean indicating whether users should see these events in their calendar without manually subscribing).
Returns the count of updated accounts.
Example Request:
GET /api/v1/accounts/:account_id/account_calendars
Returns a paginated list of account calendars for the provided account and its first level of sub-accounts. Includes hidden calendars in the response. Requires the manage_account_calendar_visibility permission.
Request Parameters:
Parameter
Type
Description
Example Request:
Returns a list of objects.
GET /api/v1/accounts/:account_id/visible_calendars_count
Return a paginated list of content shares a user has sent or received. Use self as the user_id to retrieve your own content shares. Only linked observers and administrators may view other users’ content shares.
Example Request:
Returns a list of objects.
GET /api/v1/users/:user_id/content_shares/unread_count
Return the number of content shares a user has received that have not yet been read. Use self as the user_id to retrieve your own content shares. Only linked observers and administrators may view other users’ content shares.
Restore an ePortfolio back to active that was previously deleted. Only available to admins who can moderate_user_content.
Returns an object.
This documentation is generated directly from the Canvas LMS source code, available .
Concepts
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
Assignment Groups
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Assignment Groups API
API for accessing Assignment Group and Assignment information.
Asset Processor
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Asset Processor API
1EdTech Asset Processor services: Asset Service and Asset Report Service.
get
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[providers]stringOptional
comma separated list of field names
includestringOptional
A comma separated list of resource names that will be returned in the response.
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[providers]stringOptional
comma separated list of field names
filter[providers]stringOptional
an ODATA-like query string used to filter
sort[providers]stringOptional
a comma separated list of property names specifying the sort order of the returned results
includestringOptional
A comma separated list of resource names that will be returned in the response.
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[events]stringOptional
comma separated list of field names
filter[events]stringOptional
an ODATA-like query string used to filter
sort[events]stringOptional
a comma separated list of property names specifying the sort order of the returned results
facetstringOptional
A comma separated list of facet names that you are requesting the options on.
facet_summarystringOptional
A comma separated list of facet names for which you are requesting summary information.
includestringOptional
A comma separated list of resource names that will be returned in the response.
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
{
// the unique identifier for the export
"id": 101,
// the date and time this export was requested
"created_at": "2014-01-01T00:00:00Z",
// the type of content migration: 'common_cartridge' or 'qti'
"export_type": "common_cartridge",
// attachment api object for the export package (not present before the export
// completes or after it becomes unavailable for download.)
"attachment": {"url":"https:\/\/example.com\/api\/v1\/attachments\/789?download_frd=1"},
// The api endpoint for polling the current progress
"progress_url": "https://example.com/api/v1/progress/4",
// The ID of the user who started the export
"user_id": 4,
// Current state of the content migration: created exporting exported failed
"workflow_state": "exported"
}
[{
"id": 1,
"title": "Hear ye",
"message": "Henceforth, all assignments must be...",
"posted_at": "2017-01-31T22:00:00Z",
"delayed_post_at": null,
"context_code": "course_2",
...
}]
{
// The ID of the assessment question bank.
"id": 1,
// The ID of the context (course or account) the question bank belongs to.
"context_id": 2,
// The type of context (Course or Account).
"context_type": "Course",
// The title of the question bank.
"title": "Chapter 1 Questions",
// The workflow state of the question bank.
"workflow_state": "active",
// The number of questions in the bank.
"assessment_question_count": 10,
// The combined context type and ID.
"context_code": "course_2",
// The date and time the question bank was created.
"created_at": "2013-01-01T00:00:00Z",
// The date and time the question bank was last updated.
"updated_at": "2013-01-01T00:00:00Z"
}
{
// The ID of the assessment question.
"id": 1,
// The order of the question.
"position": 1,
// The ID of the question bank this question belongs to.
"assessment_question_bank_id": 3,
// The date and time when the assessment question was created.
"created_at": "2013-01-23T23:59:00-07:00",
// The name of the question.
"question_name": "Prime Number Identification",
// The type of the question.
"question_type": "multiple_choice_question",
// The text of the question.
"question_text": "Which of the following is NOT a prime number?",
// The maximum amount of points possible received for getting this question
// correct.
"points_possible": 5,
// The comments to display if the student answers the question correctly.
"correct_comments": "That's correct!",
// The comments to display if the student answers incorrectly.
"incorrect_comments": "Unfortunately, that IS a prime number.",
// The comments to display regardless of how the student answered.
"neutral_comments": "Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.",
// The HTML version of the comments to display if the student answers the
// question correctly.
"correct_comments_html": "<p>That's correct!</p>",
// The HTML version of the comments to display if the student answers
// incorrectly.
"incorrect_comments_html": "<p>Unfortunately, that IS a prime number.</p>",
// The HTML version of the comments to display regardless of how the student
// answered.
"neutral_comments_html": "<p>Goldbach's conjecture proposes that every even integer greater than 2 can be expressed as the sum of two prime numbers.</p>",
// An array of available answers. Each answer contains id, text, html, comments,
// comments_html, and weight properties.
"answers": null,
// Variables for calculated questions. Null for other question types.
"variables": null,
// Formulas for calculated questions. Null for other question types.
"formulas": null,
// The tolerance for numerical answers. Null for non-numerical question types.
"answer_tolerance": null,
// The number of decimal places for formula results. Null for non-calculated
// question types.
"formula_decimal_places": null,
// Matching pairs for matching questions. Null for other question types.
"matches": null,
// Incorrect match options for matching questions. Null for other question
// types.
"matching_answer_incorrect_matches": null
}
// An AI Experience for interactive learning
{
// The ID of the AI experience
"id": 234,
// The title for the AI experience
"title": "Customer Service Simulation",
// The description of the AI experience
"description": "Practice customer service skills in a simulated environment",
// The AI facts for the experience (optional)
"facts": "You are a customer service representative...",
// The learning objectives for this experience
"learning_objective": "Students will practice active listening and problem-solving",
// The pedagogical guidance for the experience
"pedagogical_guidance": "A customer is calling about a billing issue",
// The current published state of the AI experience
"workflow_state": "published",
// The course this experience belongs to
"course_id": 1578941
}
{
// The internal database ID of the token.
"id": null,
// The time the token was created.
"created_at": null,
// The time the token will permanently expire, or null if it does not
// permanently expire.
"expires_at": null,
// The current state of the token. One of 'active', 'pending', 'disabled', or
// 'deleted'.
"workflow_state": null,
// Whether the token should be remembered across sessions. Only applicable for
// OAuth tokens.
"remember_access": null,
// The scopes associated with the token. If empty, there are no scope
// limitations.
"scopes": null,
// If the token was created while masquerading, this is the ID of the real user.
// Otherwise, null.
"real_user_id": null,
// The actual access token. Only included when the token is first created.
"token": null,
// A short, unique string that can be used to look up the token.
"token_hint": null,
// The ID of the user the token belongs to.
"user_id": null,
// The purpose of the token.
"purpose": null,
// If the token was created by an OAuth application, this is the name of that
// application. Otherwise, null.
"app_name": null,
// Whether the current user can manually regenerate this token.
"can_manually_regenerate": null
}
{
// The ID of the communication channel.
"id": 16,
// The address, or path, of the communication channel.
"address": "[email protected]",
// The type of communcation channel being described. Possible values are:
// 'email', 'push', 'sms'. This field determines the type of value seen in
// 'address'.
"type": "email",
// The position of this communication channel relative to the user's other
// channels when they are ordered.
"position": 1,
// The ID of the user that owns this communication channel.
"user_id": 1,
// The number of bounces the channel has experienced. This is reset if the
// channel sends successfully.
"bounce_count": 0,
// The time the last bounce occurred.
"last_bounce_at": "2012-05-30T17:00:00Z",
// The current state of the communication channel. Possible values are:
// 'unconfirmed' or 'active'.
"workflow_state": "active"
}
{
// 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"
}
// A collection of information around a specific notification of a problem
{
// The users problem summary, like an email subject line
"subject": "File upload breaking",
// long form documentation of what was witnessed
"comments": "When I went to upload a .mov file to my files page, I got an error. Retrying didn't help, other file types seem ok",
// categorization of how bad the user thinks the problem is. Should be one of
// [just_a_comment, not_urgent, workaround_possible, blocks_what_i_need_to_do,
// extreme_critical_emergency].
"user_perceived_severity": "just_a_comment",
// the email address of the reporting user
"email": "[email protected]",
// URL of the page on which the error was reported
"url": "https://canvas.instructure.com/courses/1",
// string describing the asset being interacted with at the time of error.
// Formatted '[type]_[id]'
"context_asset_string": "user_1",
// comma seperated list of roles the reporting user holds. Can be one
// [student], or many [teacher,admin]
"user_roles": "user,teacher,admin"
}
# Create error report
curl 'https://<canvas>/api/v1/error_reports' \
-X POST \
-F 'error[subject]="things are broken"' \
-F 'error[url]=http://<canvas>/courses/1' \
-F 'error[description]="All my thoughts on what I saw"' \
-H 'Authorization: Bearer <token>'
`<endpoint URI>?filter[<object of filter>]=<URL encoded filter statement>`
{
// The database ID of the ePortfolio
"id": 1,
// The user ID to which the ePortfolio belongs
"user_id": 1,
// The name of the ePortfolio
"name": "My Academic Journey",
// Whether or not the ePortfolio is visible without authentication
"public": true,
// The creation timestamp for the ePortfolio
"created_at": "2021-09-20T18:59:37Z",
// The timestamp of the last time any of the ePortfolio attributes changed
"updated_at": "2021-09-20T18:59:37Z",
// The state of the ePortfolio. Either 'active' or 'deleted'
"workflow_state": "active",
// The timestamp when the ePortfolio was deleted, or else null
"deleted_at": "2021-09-20T18:59:37Z",
// A flag indicating whether the ePortfolio has been
// flagged or moderated as spam. One of 'flagged_as_possible_spam',
// 'marked_as_safe', 'marked_as_spam', or null
"spam_status": null
}
Whether to include the number of questions in each bank.
facts
string
The AI facts for the experience.
learning_objective
Required string
The learning objectives for this experience.
pedagogical_guidance
Required string
The pedagogical guidance for the experience.
workflow_state
string
The initial state of the experience. Defaults to ‘unpublished’. Allowed values: published, unpublished
facts
string
The AI facts for the experience.
learning_objective
Required string
The learning objectives for this experience.
pedagogical_guidance
Required string
The pedagogical guidance for the experience.
workflow_state
string
The state of the experience. Allowed values: published, unpublished
token[scopes][]
Array
The scopes to associate with the token. Ignored if the default developer key does not have the “enable scopes” option enabled. In such cases, the token will inherit the user’s permissions instead.
token[scopes][]
Array
The scopes to associate with the token.
token[regenerate]
boolean
Regenerate the actual token.
communication_channel[token]
string
A registration id, device token, or equivalent token given to an app when registering with a push notification provider. Only valid for “push” type channels.
skip_confirmation
boolean
Only valid for site admins and account admins making requests; If true, the channel is automatically validated and no confirmation email or SMS is sent. Otherwise, the user must respond to a confirmation message to confirm the channel.
verbosity
string
Defaults to “full”
Allowed values: full, truncate, link_only
position
integer
The position of the bookmark. Defaults to the bottom.
data
string
The data associated with the bookmark
position
integer
The position of the bookmark. Defaults to the bottom.
data
string
The data associated with the bookmark
error[email]
string
Email address for the reporting user
error[comments]
string
The long version of the story from the user one what they experienced
error[http_env]
SerializedHash
A collection of metadata about the users’ environment. If not provided, canvas will collect it based on information found in the request. (Doesn’t have to be HTTPENV info, could be anything JSON object that can be serialized as a hash, a mobile app might include relevant metadata for itself)
content_type
The content type of the file. If not given, it will be guessed based on the file extension.
parent_folder_id
The id of the folder to store the file in. An error will be returned if this does not correspond to an existing folder. If this and parent_folder_path are sent an error will be returned. If neither is given, a default folder will be used.
parent_folder_path
The path of the folder to store the file in. The path separator is the forward slash `/`, never a back slash. The folder will be created if it does not already exist. This parameter only applies to file uploads in a context that has folders, such as a user, a course, or a group. If this and parent_folder_id are sent an error will be returned. If neither is given, a default folder will be used.
folder
[deprecated] Use parent_folder_path instead.
on_duplicate
How to handle duplicate filenames. If `overwrite`, then this file upload will overwrite any other file in the folder with the same name. If `rename`, then this file will be renamed if another file in the folder exists with the given name. If no parameter is given, the default is `overwrite`. This doesn't apply to file uploads in a context that doesn't have folders.
success_include[]
An array of additional information to include in the upload success response. See Files API for more information.
When included, searches available account calendars for the term. Returns matching results. Term must be at least 2 characters.
visible
boolean
Allow administrators with manage_account_calendar_events permission to create events on this calendar, and allow users to view this calendar and its events.
auto_subscribe
boolean
When true, users will automatically see events from this account in their calendar, even if they haven’t manually added that calendar.
search_term
string
When included, searches all descendent accounts of provided account for the term. Returns matching results. Term must be at least 2 characters. Can be combined with a filter value.
filter
string
When included, only returns calendars that are either visible or hidden. Can be combined with a search term.
An object containing the array of BlackoutDates we want to exist after this operation. For array entries, if it has an id it will be updated, if not created, and if an existing BlackoutDate id is missing from the array, it will be deleted.
{
"upload_url": "https://file-service.url/opaque",
"upload_params": {
/* unspecified parameters; contents should be treated as opaque */
},
"progress": {
/* amongst other tags, see the Progress API... */
"url": "https://canvas.example.edu/api/v1/progress/1"
"workflow_state": "running"
}
}
curl '<upload_url>' \
-F 'target_url=http://example.com/my_pic.jpg' \
<any other parameters specified in the upload_params response>
HTTP/1.1 201 Created
{
// the ID of the account associated with this calendar
"id": 204,
// the name of the account associated with this calendar
"name": "Department of Chemistry",
// the account's parent ID, or null if this is the root account
"parent_account_id": 1,
// the ID of the root account, or null if this is the root account
"root_account_id": 1,
// whether this calendar is visible to users
"visible": true,
// whether users see this calendar's events without needing to manually add it
"auto_subscribe": false,
// number of this account's direct sub-accounts
"sub_account_count": 0,
// Asset string of the account
"asset_string": "account_4",
// Object type
"type": "account",
// url to get full detailed events
"calendar_event_url": "/accounts/2/calendar_events/%7B%7B%20id%20%7D%7D",
// whether the user can create calendar events
"can_create_calendar_events": true,
// API path to create events for the account
"create_calendar_event_url": "/accounts/2/calendar_events",
// url to open the more options event editor
"new_calendar_event_url": "/accounts/6/calendar_events/new"
}
// Content shared between users
{
// The id of the content share for the current user
"id": 1,
// The name of the shared content
"name": "War of 1812 homework",
// The type of content that was shared. Can be assignment, discussion_topic,
// page, quiz, module, or module_item.
"content_type": "assignment",
// The datetime the content was shared with this user.
"created_at": "2017-05-09T10:12:00Z",
// The datetime the content was updated.
"updated_at": "2017-05-09T10:12:00Z",
// The id of the user who sent or received the content share.
"user_id": 1578941,
// The user who shared the content. This field is provided only to receivers; it
// is not populated in the sender's list of sent content shares.
"sender": {"id":1,"display_name":"Matilda Vargas","avatar_image_url":"http:\/\/localhost:3000\/image_url","html_url":"http:\/\/localhost:3000\/users\/1"},
// An Array of users the content is shared with. This field is provided only to
// senders; an empty array will be returned for the receiving users.
"receivers": [{"id":1,"display_name":"Jon Snow","avatar_image_url":"http:\/\/localhost:3000\/image_url2","html_url":"http:\/\/localhost:3000\/users\/2"}],
// The course the content was originally shared from.
"source_course": {"id":787,"name":"History 105"},
// Whether the recipient has viewed the content share.
"read_state": "read",
// The content export record associated with this content share
"content_export": {"id":42}
}
curl -X POST 'https://<canvas>/api/v1/users/self/content_shares/123/add_users?receiver_ids[]=789'
curl -X PUT 'https://<canvas>/api/v1/users/self/content_shares/123?read_state=read'
// Blackout dates are used to prevent scheduling assignments on a given date in
// course pacing.
{
// the ID of the blackout date
"id": 1,
// the context owning the blackout date
"context_id": 1,
"context_type": "Course",
// the start date of the blackout date
"start_date": "2022-01-01",
// the end date of the blackout date
"end_date": "2022-01-02",
// title of the blackout date
"event_title": "some title"
}
{
// The database ID of the ePortfolio
"id": 1,
// The ePortfolio ID to which the entry belongs
"eportfolio_id": 1,
// The positional order of the entry in the list
"position": 1,
// The name of the ePortfolio
"name": "My Academic Journey",
// The user entered content of the entry
"content": "A long time ago...",
// The creation timestamp for the ePortfolio
"created_at": "2021-09-20T18:59:37Z",
// The timestamp of the last time any of the ePortfolio attributes changed
"updated_at": "2021-09-20T18:59:37Z"
}
(a) If sections were asked for and the topic is specific to certain
course sections sections, includes the number of users in each
section. (as part of the section json asked for above)
(b) Else, includes at the root level the total number of users in the
topic's context (group or course) that the topic applies to.
not
Logical negation. E.g. not propertyX in ('a', 'b, 'c')
Comparator
eq
Equals. E.g. propertyX eq 'apple'
ne
Not equals. E.g. propertyX ne 'fruit'
gt
Greater than. E.g. propertyX gt 5
ge
Greater than or equal to. E.g. propertyX ge 5
lt
Less than. E.g. propertyX lt 5
le
Less than or equal to. E.g. propertyX le 5
in
The value of the specified property is in the supplied list of values. E.g. propertyX in ('value1', 'value2', 'value3')
Conditional
and
Combine two conditions and return true if both are true, otherwise false. E.g. propertyX eq 5 and propertyY ne 'A'
or
Combine two conditions and return true if either are true, otherwise false. E.g. propertyX eq 5 or propertyY ne 'A'
.
5th grade math and 7th grade language arts Standards
Returns the paginated list of assignment groups for the current context. The returned groups are sorted by their position field.
Request Parameters:
Parameter
Type
Description
include[]
string
Associations to include with the group. “discussion_topic”, “all_dates”, “can_edit”, “assignment_visibility” & “submission” are only valid if “assignments” is also included. “score_statistics” requires that the “assignments” and “submission” options are included. The “assignment_visibility” option additionally requires that the Differentiated Assignments course feature be turned on. If “observed_users” is passed along with “assignments” and “submission”, submissions for observed users will also be included as an array. The “peer_review” option requires that the Peer Review Grading course feature be turned on and that “assignments” is included.
If “assignments” are included, optionally return only assignments having their ID in this array. This argument may also be passed as a comma separated string.
Associations to include with the group. “discussion_topic” and “assignment_visibility” and “submission” are only valid if “assignments” is also included. “score_statistics” is only valid if “submission” and “assignments” are also included. The “assignment_visibility” option additionally requires that the Differentiated Assignments course feature be turned on.
The ID of an active Assignment Group to which the assignments that are currently assigned to the destroyed Assignment Group will be assigned. NOTE: If this argument is not provided, any assignments in this Assignment Group will be deleted.
Creates a report for a given Canvas-managed asset (such as a submission attachment).
Returns an HTTP 201 (Created) on success.
Request Parameters:
Parameter
Type
Description
assetId
string
The UUID of the asset to which the report applies. Canvas will supply this to the tool in the the LtiAssetProcessorSubmissionNotice.
errorCode
string
A machine-readable code indicating the cause of the failure, for reports with a processingProgress value of Failed. The following standard error codes are available, but tools may use their own (in which case the tool may provide human-readable information in the comment field): UNSUPPORTED_ASSET_TYPE, ASSET_TOO_LARGE, ASSET_TOO_SMALL, EULA_NOT_ACCEPTED, DOWNLOAD_FAILED
Remove the EULA acceptance status for all users within the current deployment. This will allow a tool to reset the EULA acceptance status for all users, and force them to accept the EULA again in the case that the EULA has changed.
This documentation is generated directly from the Canvas LMS source code, available on Github.
Duration of server side request processing in milliseconds.
typestring · enumOptional
Literal "providers" - JSON API requirement.
Possible values:
idstringOptional
Synonym for our GUID field required by the JSON API standard.
guidstringOptional
Unique identifier of the object.
descrstringOptional
The Provider name.
itemsstring · enumOptionalPossible values:
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestring · enumOptional
Literal "providers" - JSON API requirement.
Possible values:
idstringOptional
Synonym for our GUID field required by the JSON API standard.
guidstringOptional
Unique identifier of the object.
descrstringOptional
The Provider name.
itemsstring · enumOptionalPossible values:
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/providers/{guid}
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestring · enumOptional
Literal "providers" - JSON API requirement.
Possible values:
idstringOptional
Synonym for our GUID field required by the JSON API standard.
guidstringOptional
Unique identifier of the object.
descrstringOptional
The Provider name.
itemsstring · enumOptionalPossible values:
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestring · enumOptional
Literal "providers" - JSON API requirement.
Possible values:
idstringOptional
Synonym for our GUID field required by the JSON API standard.
guidstringOptional
Unique identifier of the object.
descrstringOptional
The Provider name.
itemsstring · enumOptionalPossible values:
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
400
Bad Request
application/json
401
Authentication Error
application/json
get
/providers
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
countnumberOptional
facetstringOptional
descrstringOptional
codestringOptional
guidstringOptional
countnumberOptional
document_guidstringOptional
The GUID of the document in question.
guidstringOptional
AB GUID for this Event.
date_utcstringOptional
The date/time of this Event in UTC.
namestringOptional
The name of the affected property (e.g. statement.descr)
previous_valuestringOptional
An variant whose type matches the affected property and holds the value of the property before the change. Currently, this is limited to string or number values, but it is possible this is extended to complex types in the future (like arrays and objects). This can be null in cases where AB Connect is not currently tracking previous values for some Events. Note that since this field is a variant type, it cannot be included in filter statements.
new_valuestringOptional
An variant whose type matches the affected property and holds the value of the property after the change. Currently, this is limited to string or number values, but it is possible this is extended to complex types in the future (like arrays and objects). Note that since this field is a variant type, it cannot be included in filter statements.
section_guidstringOptional
The GUID of the section in question.
seqnumberOptional
The sequence number for this event
targetstring · enumOptional
The focus of this change event.
Possible values:
change_typestringOptional
typestringOptional
Literal "events" - JSON API requirement.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
400
Bad Request
application/json
401
Authentication Error
application/json
get
/events
get
/asset_definitions/{guid}
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestring · enumOptional
Literal "asset_definitions" - JSON API requirement.
Possible values:
typestringOptional
Literal "asset_definitions" - JSON API requirement.
asset_typestringOptional
The Asset Definition name.
filterablestringOptional
The flag to determine if this property is filterable or not.
seqnumberOptional
The position of this property in this asset type.
labelstringOptional
The actual name of this property.
idstringOptional
API identifier for the field which uniquely identifies the entity to be filtered by. This is the property you would use when constructing your filters statement.
namestringOptional
The API-recognized name for the entity you are using to filter. This is the property you would use when asking for facets.
idstringOptional
The API Identifier for the entity-unique property in the facets response. This is the property you would use when constructing your filter statement and thus must correspond with the values in this entity’s field.id.
namestringOptional
The API Identifier for the human-readable property in the facets response.
guidstringOptional
Unique identifier of the object.
400
Bad Request
application/json
401
Authentication Error
application/json
get
/asset_definitions
get
Path parameters
guidstringRequired
guid of specified concept
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[concepts]stringOptional
comma separated list of field names
Responses
200
Successful operation
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[concepts]stringOptional
comma separated list of field names
filter[concepts]stringOptional
an ODATA-like query string used to filter
sort[concepts]stringOptional
a comma separated list of property names specifying the sort order of the returned results
facetstringOptional
A comma separated list of facet names that you are requesting the options on.
facet_summarystringOptional
A comma separated list of facet names for which you are requesting summary information.
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standards]stringOptional
comma separated list of field names
includestringOptional
A comma separated list of resource names that will be returned in the response. Standards have relationships with other resources (e.g. other Standards, Topics and Concepts). By default, those related resources are returned as references to other endpoints and only their IDs are included in the response. If you list the related resources by their relationship name in the include statement, the properties of the related resources are included as well.
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
or
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
or
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/standards/{guid}
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standards]stringOptional
comma separated list of field names
filter[standards]stringOptional
an ODATA-like query string used to filter
sort[standards]stringOptional
a comma separated list of property names specifying the sort order of the returned results
facetstringOptional
A comma separated list of facet names that you are requesting the options on.
facet_summarystringOptional
A comma separated list of facet names for which you are requesting summary information.
includestringOptional
A comma separated list of resource names that will be returned in the response.
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
countnumberOptional
facetstringOptional
descrstringOptional
codestringOptional
guidstringOptional
countnumberOptional
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
or
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
or
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
get
/standards
get
Path parameters
guidstringRequired
guid of specified topic
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[topics]stringOptional
comma separated list of field names
includestringOptional
A comma separated list of resource names that will be returned in the response.
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
or
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/topics/{guid}
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[topics]stringOptional
comma separated list of field names
filter[topics]stringOptional
an ODATA-like query string used to filter
sort[topics]stringOptional
a comma separated list of property names specifying the sort order of the returned results
facetstringOptional
A comma separated list of facet names that you are requesting the options on.
facet_summarystringOptional
A comma separated list of facet names for which you are requesting summary information.
includestringOptional
A comma separated list of resource names that will be returned in the response.
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
countnumberOptional
facetstringOptional
descrstringOptional
codestringOptional
guidstringOptional
countnumberOptional
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
or
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
get
/topics
Working with Related Object
While the definition of a Standard or Topic can be helpful in adding value to your system, there is a lot of power in the relationships available in AB Connect. E.g. The Topics covered by a Standard are represented by a relationship between the Standard and one or more Topics. Assets are related to Standards when they are aligned. Standards are related to other Standards (like Peers).
AB Connect exposes these relationships via the data.relationships property. This section explains how to access the power of these relationships.
Addressing Meta Properties on Relationships
Some relationships in AB Connect have properties. E.g. Relationships between Assets and Standards have a disposition, prediction score, dates, etc. These properties are represented in the JSON as meta properties on the relationship. AB Connect allows you to address the relationship meta properties for use in either or . When referencing these properties, include meta. as part of the property path. E.g. fields[assets]=alignments.meta.date_created_utc
Paging Related Objects
Resources can have many related objects - sometimes thousands. In order to maintain system performance, AB Connect limits the number of related objects that are returned when requesting a resource. Use paging on the relationship endpoint to retrieve more (or all) of the related objects.
Some relationships have limited cardinality. E.g. a Standard can have zero or one "parent". Other relationships are not limited but commonly have a small set of related entities. E.g. a Standard typically has a handful of Concepts, however in some extreme situations a Standard may have 50 Concepts. To optimize transmissions, AB Connect will return up to the first 25 related objects but if there are more than 25 related objects, AB Connect returns the first 10 relationships with paging URLs. Note that neither the page size (limit) nor the offset can be changed at this point - but can be changed on the relationship endpoint.
Here is an example of a response showing a Standard's related Peers and the paging URLs to retrieve more peer data. To get this data, you might make a call like:
To load the next page of Peers related to the Standard (00003506-B001-11DA-93BA-9A7258581090), follow the next URL:
The data available on the relationship endpoints is a conflation between the related object (attributes and relationships) and the relationship properties (meta).
Objects returned on the relationship endpoint do not support accessing their relationships nor including the further related data. For example, when viewing an Asset, you can see the alignments for that Asset, include related aligned Standards and page through the alignments at the relationship endpoint (assets/GUID/alignments). However, when you are viewing the properties of the aligned Standards on the alignment endpoint (assets/GUID/alignments), you can not include peers to those alignments nor can you page the peer standards. If you need to dig deeper into the aligned standards, you must request the data via the Standards endpoint.
See for details on working with the relationship endpoints.
Including Related Resource Properties
The JSON API standard supports an include argument in the query string. The value of the include argument is a comma separated list of relationships on the specified endpoint. If the include statement appears in the query string, the resources returned in the relationships section and named in the statement are included in the response. This helps the caller avoid a second set of calls to retrieve the object details.
Note that it is important that you specify the relationship name in the include statement rather than the object type. For example, when retrieving Standards there are a number of relationships that are available: parent, ancestors, children, derivatives, origins, etc. Most of them are relationships to other Standards. If you asked the system to include "standards", it would not know which set you are actually requesting. You must explicitly request children (for example).
The generic form of the statement is:
For example:
Will return the details of the Standards related to the requested Topic.
Notes:
If you include a relationship that does not appear in the request as a "relationship" by being included through the fields argument then the include block will be left out of the response.
E.g. https://api.abconnect.instructure.com/rest/v4.1/standards/1F9D5A8A-7053-11DF-8EBF-BE719DFF4B22?include=ancestors will NOT return the ancestors resources because that relationship is not delivered.
Filtering Related Objects
Sometimes it is convenient to filter the objects that are returned in the relationship. Meta properties on the relationship can always be used in filtering related objects. However, there are some scenarios where it is helpful to filter the related objects on key properties. E.g. one may only be interested in California Standards aligned to an Asset. To implement filtering related objects on all properties presents architectural challenges so to strike a balance and facilitate common use cases, AB Connect allows the caller to filter related object on specific properties on certain relationships.
When filtering on related objects, use the relationship name in the filter statement. E.g.
Will return math Assets and the alignments relationship for each Asset will only include Texas Standards aligned after March 12th 2020.
Filtering Objects Related to Assets
This section describes properties that can be be used when filtering objects related to the Asset.
Aligned Standards
When filtering aligned Standards, use the relationship name in the filter statement. E.g.
Supported properties include:
ancestors.id
concepts.context
concepts.descr
Notes:
deleted_alignments are filterable in a similar fashion as alignments.
You can use any of the "meta" properties on the relationship in the filtering - e.g. meta.score, meta.tags, etc. See the relationship definition for a complete list of meta properties.
Topics
Only data associated with accepted and predicted Topics are filterable. Filtering on Topics properties will not return any rejected Topics. The only supported property is the Topic description.
Note that the relationship and type of Topics is the same in this instance:
Concepts
Only data associated with central and relevant Concepts are filterable. Filtering on Concept properties will not return any not_applicable or avoid Concepts. The only supported properties are the Concept description and context.
Note that the relationship and type of Concepts is the same in this instance:
Filtering Concepts Related to Standards
When retrieving Concepts related to a Standard, you can filter the list on context and description.
Filtering Resources by Properties on Related Resources
One common need is to search across object relationships - for example, search for Assets based on properties of related Standards. Since this is a common need, AB Connect supports searching Assets based on key properties of related entities. E.g.
This will return Assets aligned to Standards in California. This can be combined with other properties on the Asset or related entities. E.g. to find Assets related to California Standards on a particular Topic
And combining that with Asset properties...
The text fields on the related entities are also indexed with the Asset full text search. This strengthens the Asset full text search in two ways.
When searching Assets for a key word or phrase, the engine will respond with Assets that are associated with that word or phrase through relationships and not just with the Asset properties.
Full text search results include the text of related entities when ranking results. E.g. If an Asset is related to multiple Concepts, Topics or Standards that contain the word "triangle" it will appear higher in the search results than an Asset that only mentions the word in a text field or has a few related entities that contain "triangle".
The following list shows related entity properties that can be included in an Asset search:
Standards
alignments.ancestors.id
alignments.concepts.context - this field is also included in full text searches once for each Standard that has this Concept in a Key Idea
Notes:
Assets can be filtered by deleted_alignments properties in a similar fashion as alignments, however, no deleted_alignments properties are included in an Asset's full text search.
The Academic Benchmarks Topics and Concepts are licensed separately. See the section on for a discussion on the licensing required for access to those taxonomies.
It is also possible to search on the properties of the relationship between Assets and entities with simple relationships to Assets (Standards, Topics, Concepts, etc.). In order to do that, address the relationship properties as if they were properties on the related entity itself. E.g. you can filter on accepted Standards with alignments.meta.disposition eq 'accepted'. To search for Assets that have accepted relationships with a specific standard, your filter statement will look like:
Note that you can use any of the "meta" properties on the relationship in the filtering - e.g. alignments.meta.score, alignments.meta.tags, etc. See the relationship definition for a complete list of meta properties.
Filtering Standards and Relationships
Like Assets, Standards can also be filtered by some key properties on related entities. The following list shows related entity properties that can be included in a Standard search:
Concepts
concepts.context - this field is also included in full text searches
concepts.descr - this field is also included in full text searches
Filtering by Other Properties and Relationships to Other Resources
To search for resources by properties on related entities other than those listed above, use the search capability to locate the related entities of interest, build a list of related entities and then search the resource by the related entity IDs. For example, if you'd like to find Standards in Virginia that cover Exponents in the 8th grade, first search for the Topic. Topics are grade banded so you'll want to include the grade in your filter to ensure you are getting the correct Topic for the grade.
The result is Topic 06EA4018-32ED-11E0-8DE3-079AD51F4EFC. Then search the Standards for items in Virginia related to this Topic.
If the result of the first search resulted in multiple related Topics (say you also wanted to include Standards related to "Problem Solving"), you can include them all in the Standards filter using the "IN" clause. E.g.
Although we use Standards and their relationships to Topics in this example, the same approach can be taken for searching for any objects based on their relationship to other objects. E.g.
Locating Standards related to Concepts or other Standards
Locating Topics related to Standards or other Topics
Locating Assets related to other Assets or to properties of Standards, Topics or Concepts not listed above.
When searching across relationships and specifying the filter criteria, the filter property name is based on the relationship rather than the related object type. For example, standards is a resource type and the Standards endpoint has relationships with other Standards. However, those relationships are named parent, ancestors, origins, derivatives, children, peers, etc. If the filter referenced the type instead of the relationship name, the filter would read filter[standards]=(standards.id eq 'F97EA8C2-D9AE-11E2-8230-99ABD51F4EFC') and the system would have no way to know which relationship you were filtering on. Instead, if you were looking for Standards that were under a given Standard (i.e. Standards that had a certain Standard as an ancestor
Facets
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=* - Return all of the facets available for the endpoint. See . Note that using an asterisk can have an impact on system performance so we strongly recommend you use the asterisk only for discovery when you are learning the API. To ensure the use of wildcards with the facet_summary parameter does not impact overall system performance, such calls are throttled to 2 per second.
facet_summary=<CSV list of facet attributes> - Return the summaries of the listed facets.
The facets that are available vary by endpoint and licensing. While some facets values offer additional properties, all of them have at least a guid and descr property. Note that Topic facets also offer information about their parents so a calling application can easily assemble the required tree without the added overhead of calls to the Topics endpoint.
Using Facets as an Entry Point for Browsing Standards
By way of example, let's examine the facet capability of the Standards endpoint. This can be used as a convenient starting point for users browsing for Standards. It can also be used as a means for examining "categories" of Standards in your license. To get started, if you call the endpoint requesting all facet summaries without any filtering, the system will respond with the types of facets available and the number of elements in each facet. For convenience, we'll set the limit to 0 here so the system doesn't bother to respond with any actual Standards because at this point, we are only interested in the facets themselves which come back via the meta portion of the response.
The facet counts respect both your license limitations and the current filter. In this case, we are not specifying a filter, so the counts reflect our licensing.
If you wanted to build a user interface that offers the user control over each facet in filtering the Standards, you could request the elements for each facet and populate lists with the results. You may find that offering 10 facets is overwhelming for your users so you may want to select a few key facets. Perhaps we start by allowing the users to select an authority and subject. Let's retrieve the details of those two facets. The facet "names" are the values of the facet properties - in this case, document.publication.authorities and disciplines.subjects. Note that you can see in the response above that there are 17 subjects and 54 authorities in this license (although yours will vary). The example response below has been simplified to improve readability.
Once a user has selected an authority (Georgia DOE) and subject (Science), you may want to offer them a list of relevant strands. Note that there are 111 strands in this sample license. Let's limit the scope to Georgia DOE and Science and get the list of relevant strands to offer the user.
Now you see that there are only 7 relevant strands. One thing to note: the detail.count property is the number of Standards that match the associated criteria. For example, there are 28 Space Science related Standards in Georgia.
You can continue this approach to help the user narrow the Standards down to a manageable count and then present them to the user for selection.
Using Facets as an Entry Point for Browsing Assets
Using faceting on Assets is similar to that of Standards with one major exception. Asset faceting can include custom attributes. E.g. if your Assets represent assessment items and you have an item_type field that may contain values like "Multiple Choice", "Essay", etc. you can request the facet summary by explicitly requesting facet_summary=custom_attributes.item_type and/or retrieve the details with facet=custom_attributes.item_type. The custom attributes may contain unique values (like a URL or external ID) and calculating the facets can impact performance.
Notes
Although this section focused on the Standards endpoint as an example, all endpoints except Clarifier support faceting.
The facet results appear in the meta section of the JSON API response.
Facet summaries that have high counts (counts in the thousands) may not be exact - they are approximate for performance reasons. If you need an exact count, you must request the facet. The count returned with the facet is accurate as are the counts returned with each facet value.
This documentation is generated directly from the Canvas LMS source code, available .
Examples
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.
Download the .
Unzip the file into a folder on your system.
Run the following commands in the folder where you placed the unzipped source.
npm install
To obtain a production widgets bundle, follow these steps:
For a bash shell:
NODE_ENV=production npm run build
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.
Requesting Additional Properties in the Response
By default, if the fields argument is not included in the request, AB Connect responds with the object ID and type. In order to request that AB Connect return additional properties in its response, use the fields URL parameter. The form is fields[<type>]=<CSV list of properties>.
To illustrate the usage, let's take a look at the properties of a Standard and how use of the fields parameter affects the system response. Let's begin with the default response.
As you can see, the response does not include much useful information. Let's make the call again asking just for the main text of the Standard, its number and the AB standard_type.
Conversely, if you really want it ALL, you can use an asterisk to indicate that you want the system to give you EVERYTHING! Note that this can have an impact on system performance so we strongly recommend you use the asterisk only for discovery when you are learning the API. To ensure the use of wildcards with the
Account Reports
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Account Reports API
API for accessing account reports.
Account Notifications
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Account Notifications API
API for account notifications.
Enrollment Terms
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Enrollment Terms API
API for viewing enrollment terms. For all actions, the specified account must be a root account and the caller must have permission to manage the account (when called on non-root accounts, the errorwill be indicate the appropriate root account).
Discovery Pages
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Discovery Pages API
A DiscoveryPage object looks like:
`(disciplines.subjects.code eq 'MATH' and education_levels.grades.code eq '5' and document.publication.authorities.descr eq 'Kentucky DOE' and utilizations.type eq 'alignable')`
`filter[standards]=(query(statement.descr, 'fractions') and query(statement.descr, 'adding'))`
`filter[standards]=(query('adding fractions'))`
`filter[standards]=(query('don\'t'))`
`filter[assets]=isempty(disciplines.subjects)`
{
// Number of lowest scores to be dropped for each user.
"drop_lowest": 1,
// Number of highest scores to be dropped for each user.
"drop_highest": 1,
// Assignment IDs that should never be dropped.
"never_drop": [33, 17, 24]
}
{
// the id of the Assignment Group
"id": 1,
// the name of the Assignment Group
"name": "group2",
// the position of the Assignment Group
"position": 7,
// the weight of the Assignment Group
"group_weight": 20,
// the sis source id of the Assignment Group
"sis_source_id": "1234",
// the integration data of the Assignment Group
"integration_data": {"5678":"0954"},
// the assignments in this Assignment Group (see the Assignment API for a
// detailed list of fields)
"assignments": [],
// the grading rules that this Assignment Group has
"rules": null
}
Apply assignment overrides for each assignment, defaults to true.
grading_period_id
integer
The id of the grading period in which assignment groups are being requested (Requires grading periods to exist.)
scope_assignments_to_student
boolean
If true, all assignments returned will apply to the current user in the specified grading period. If assignments apply to other students in the specified grading period, but not the current user, they will not be returned. (Requires the grading_period_id argument and grading periods to exist. In addition, the current user must be a student.)
grading_period_id
integer
The id of the grading period in which assignment groups are being requested (Requires grading periods to exist on the account)
group_weight
number
The percent of the total grade that this assignment group represents
sis_source_id
string
The sis source id of the Assignment Group
integration_data
Object
The integration data of the Assignment Group
group_weight
number
The percent of the total grade that this assignment group represents
sis_source_id
string
The sis source id of the Assignment Group
integration_data
Object
The integration data of the Assignment Group
rules
string
The grading rules that are applied within this assignment group See the Assignment Group object definition for format
indicationAlt
string
Alternate text representing the meaning of the indicationColor for screen readers or as a tooltip over the indication color.
indicationColor
string
A hex (#RRGGBB) color code the tool wishes to use indicating the outcome of an asset’s report.
priority
integer
A number from 0 (meaning “good” or “success”) to 5 (meaning urgent or time-critical notable features) indicating the tool’s perceived priority of the report. If a priority is not known or applicable, the tool should use the value 0.
processingProgress
string
Indicates the status of the report. Should be one of the following: Processed, Processing, PendingManual, Failed, NotProcessed, NotReady. If an unrecognized value is given, the value will be stored, but will be treated by Canvas as NotReady.
result
string
A short string (16 characters or fewer) that briefly describes the successful result of the processing. This should be provided if processingProgress is Processed, and not provided otherwise.
timestamp
string
An ISO8601 date time value with microsecond precision. Reports with newer timestamps for the same asset and report type supersede previously submitted reports with older (or equal) timestamps. Likewise, if the timestamp provided is older than the latest timestamp for an existing report (of same asset and type), the new report will be ignored and the endpoint will return an HTTP 409 (Conflict).
title
string
A human-readable title for the report, to be displayed to the user.
type
string
An opaque value representing the type of report.
visibleToOwner
boolean
A boolean value indicates whether the indicator and report should be visible to the user who owns the asset being reported on. If no value is provided, the platform should assume a default value of false
timestamp
string
The timestamp represents the time at which the user accepted or declined the EULA. This timestamp must be formatted as an ISO 8601 date time.
E.g. https://api.abconnect.instructure.com/rest/v4.1/standards/1F9D5A8A-7053-11DF-8EBF-BE719DFF4B22?fields[standards]=ancestors&include=ancestors will have the ancestors listed in the relationships and their details in the included block
disciplines.subjects.descr
disciplines.subjects.guid
document.descr
document.guid
document.publication.descr
document.publication.guid
document.publication.authorities.descr
document.publication.authorities.guid
document.publication.regions.descr
document.publication.regions.guid
education_levels.grades.descr
education_levels.grades.guid
number.raw
number.enhanced
number.prefix_enhanced
section.guid
section.descr
status
statement.descr
topics.descr
alignments.concepts.descr - this field is also included in full text searches once for each Standard that has this Concept in a Key Idea
alignments.document.disciplines.subjects.descr
alignments.document.disciplines.subjects.guid
alignments.document.descr - this field is also included in full text searches
alignments.document.guid
alignments.document.publication.descr - this field is also included in full text searches
alignments.document.publication.guid
alignments.document.publication.authorities.descr
alignments.document.publication.authorities.guid
alignments.document.publication.regions.descr
alignments.document.publication.regions.guid
alignments.education_levels.grades.descr
alignments.education_levels.grades.guid
alignments.number.raw
alignments.number.enhanced
alignments.number.prefix_enhanced
alignments.section.guid
alignments.section.descr - this field is also included in full text searches
alignments.status
alignments.statement.descr - this field is also included in full text searches
alignments.topics.descr - this field is also included in full text searches once for each Standard that covers this Topic
Topics - Only data associated with accepted and predicted Topics are searchable on the Asset
topics.descr - this field is also included in full text searches
Concepts - Only data associated with central and relevant Concepts are searchable on the Asset
concepts.context - this field is also included in full text searches
concepts.descr - this field is also included in full text searches
If you do not supply a facet_summary parameter, the system does not return any facet information.
If the facet or facet_summary arguments are combined with filter criteria, the results respect the filter requirements.
AB Connect does not support paging of facet data.
When requesting facets with a large number of values (count > 10,000) only the first 10,000 entries are returned. In general faceting on a large number of values has performance implications and should be avoided.
A quick way to retrieve facet information without cluttering the response with actual Standards data is to use the limit argument and set the limit to 0. For example:
https://api.abconnect.instructure.com/rest/v4.1/standards?limit=0&facet_summary=* returns a minimal set of data including the facets and counts for your license. You can use this as a starting point if you are dynamically building a UI to allow users to select facet criteria.
https://api.abconnect.instructure.com/rest/v4.1/standards?limit=0&filter[standards]=(document.publication.authorities.descr%20eq%20%27Kentucky%20DOE%27)&facet_summary=* returns the facets and counts for Kentucky DOE Standards.
`filter[assets]=(alignments.document.publication.authorities.descr eq 'California DOE' and alignments.topics.descr eq 'Exponents and Roots')`
`filter[assets]=(alignments.document.publication.authorities.descr eq 'California DOE' and alignments.topics.descr eq 'Exponents and Roots' and education_levels.grades.code eq '8')`
`filter[assets]=(alignments.id eq '0029A5C3-3C0C-4127-9766-C44E5E255C26' and alignments.meta.disposition eq 'accepted')`
`filter[topics]=(query(descr, 'exponents') and education_levels.grades.code eq '8')`
`filter[standards]=(document.publication.authorities.descr eq 'Virginia DOE' and education_levels.grades.code eq '8' and topics.id eq '06EA4018-32ED-11E0-8DE3-079AD51F4EFC')`
`filter[standards]=(document.publication.authorities.descr eq 'Virginia DOE' and education_levels.grades.code eq '8' and topics.id in ('06EA4018-32ED-11E0-8DE3-079AD51F4EFC','067C7C8E-EBE5-11E5-AE48-F5189AAB8BA3'))`
{
// The ID of the custom gradebook column
"id": 2,
// When true, this column's visibility will be toggled in the Gradebook when a
// user selects to show or hide notes
"teacher_notes": false,
// header text
"title": "Stuff",
// column order
"position": 1,
// won't be displayed if hidden is true
"hidden": false,
// won't be editable in the gradebook UI
"read_only": true
}
// ColumnDatum objects contain the entry for a column for each user.
{
"content": "Nut allergy",
"user_id": 2
}
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
countnumberOptional
facetstringOptional
descrstringOptional
codestringOptional
guidstringOptional
countnumberOptional
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
Generates a report instance for the account. Note that “report” in the request must match one of the available report names. To fetch a list of available report names and parameters for each report (including whether or not those parameters are required), see List Available Reports.
Request Parameters:
Parameter
Type
Description
parameters[]
Hash
The parameters will vary for each report. To fetch a list of available parameters for each report, see . A few example parameters have been provided below. Note that the example parameters provided below may not be valid for every report.
parameters[skip_message]
boolean
If true, no message will be sent to the user upon completion of the report.
Returns a list of all global notifications in the account for the current user Any notifications that have been closed by the user will not be returned, unless a include_past parameter is passed in as true. Admins can request all global notifications for the account by passing in an include_all parameter.
Request Parameters:
Parameter
Type
Description
include_past
boolean
Include past and dismissed global announcements.
include_all
boolean
Include all global announcements, regardless of user’s role or availability date. Only available to account admins.
If the current user no longer wants to see this account notification, it can be closed with this call. This affects the current user only.
If the current user is an admin and they pass a remove parameter with a value of “true”, the account notification will be destroyed. This affects all users.
Update or create the discovery page configuration for the domain root account. This is a full replacement - provide the complete configuration including primary, secondary, and active fields. Any fields omitted will be removed.
Returns a short-lived RS256-signed JWT containing the discovery page button link configuration, suitable for sending to the identity service preview iframe via postMessage.
A discovery_page configuration must be provided in the request body. Omitting it returns a 400 Bad Request.
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 .
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.
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:
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.
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.
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.
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
Course Pace
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Course Pace API
API for accessing and building Course Paces.
Asset Collections
When there is a need to quickly identify and refer to a filtered collection of assets, the "Asset Collection" is what provides a solution. Asset Collection stores the filters object with a name and a guid as reference.
The "filters" is a JSON object that stores "assetType" and "facets". Searching filters are generated from this object to narrow down the result set the client wants to use.
GET /rest/v4.1/concepts/{guid}?partner.id=text&auth.signature=text&auth.expires=text HTTP/1.1
Host: api.abconnect.instructure.com
Accept: */*
GET /rest/v4.1/concepts?partner.id=text&auth.signature=text&auth.expires=text HTTP/1.1
Host: api.abconnect.instructure.com
Accept: */*
{
// The unique identifier for the report.
"id": 1,
// The type of report.
"report": "sis_export_csv",
// The url to the report download.
"file_url": "https://example.com/some/path",
// The attachment api object of the report. Only available after the report has
// completed.
"attachment": null,
// The status of the report
"status": "complete",
// The date and time the report was created.
"created_at": "2013-12-01T23:59:00-06:00",
// The date and time the report started processing.
"started_at": "2013-12-02T00:03:21-06:00",
// The date and time the report finished processing.
"ended_at": "2013-12-02T00:03:21-06:00",
// The time (in seconds) the report has been waiting to run, has been running so
// far, or took to run to completion, depending on its current state.
"run_time": 33.3,
// The report parameters
"parameters": {"course_id":2,"start_at":"2012-07-13T10:55:20-06:00","end_at":"2012-07-13T10:55:20-06:00"},
// The progress of the report
"progress": 100,
// This is the current line count being written to the report. It updates every
// 1000 records.
"current_line": 12000,
// The user that initiated the account report. See the Users API for details.
"user": null
}
// The parameters returned will vary for each report.
{
// The canvas id of the term to get grades from
"enrollment_term_id": 2,
// If true, deleted objects will be included. If false, deleted objects will be
// omitted.
"include_deleted": false,
// The id of the course to report on
"course_id": 2,
// The sort order for the csv, Options: 'users', 'courses', 'outcomes'.
"order": "users",
// If true, user data will be included. If false, user data will be omitted.
"users": false,
// If true, account data will be included. If false, account data will be
// omitted.
"accounts": false,
// If true, term data will be included. If false, term data will be omitted.
"terms": false,
// If true, course data will be included. If false, course data will be omitted.
"courses": false,
// If true, section data will be included. If false, section data will be
// omitted.
"sections": false,
// If true, enrollment data will be included. If false, enrollment data will be
// omitted.
"enrollments": false,
// If true, group data will be included. If false, group data will be omitted.
"groups": false,
// If true, data for crosslisted courses will be included. If false, data for
// crosslisted courses will be omitted.
"xlist": false,
"sis_terms_csv": 1,
"sis_accounts_csv": 1,
// If true, enrollment state will be included. If false, enrollment state will
// be omitted. Defaults to false.
"include_enrollment_state": false,
// Include enrollment state. Defaults to 'all' Options: ['active'| 'invited'|
// 'creation_pending'| 'deleted'| 'rejected'| 'completed'| 'inactive'| 'all']
"enrollment_state": ["all"],
// The beginning date for submissions. Max time range is 2 weeks.
"start_at": "2012-07-13T10:55:20-06:00",
// The end date for submissions. Max time range is 2 weeks.
"end_at": "2012-07-13T10:55:20-06:00"
}
curl -H 'Authorization: Bearer <token>' \
-X PUT \
https://<canvas>/api/v1/accounts/<account_id>/reports/<report_type>/<id>/abort
{
// The subject of the notifications
"subject": "Attention Students",
// The message to be sent in the notification.
"message": "This is a test of the notification system.",
// When to send out the notification.
"start_at": "2013-08-28T23:59:00-06:00",
// When to expire the notification.
"end_at": "2013-08-29T23:59:00-06:00",
// The icon to display with the message. Defaults to warning.
"icon": "information",
// (Deprecated) The roles to send the notification to. If roles is not passed
// it defaults to all roles
"roles": ["StudentEnrollment"],
// The roles to send the notification to. If roles is not passed it defaults to
// all roles
"role_ids": [1],
// The author of the notification. Available only to admins using include_all.
"author": {"id":1,"name":"John Doe"}
}
{
// The unique identifier for the enrollment term.
"id": 1,
// The SIS id of the term. Only included if the user has permission to view SIS
// information.
"sis_term_id": "Sp2014",
// the unique identifier for the SIS import. This field is only included if the
// user has permission to manage SIS information.
"sis_import_id": 34,
// The name of the term.
"name": "Spring 2014",
// The datetime of the start of the term.
"start_at": "2014-01-06T08:00:00-05:00",
// The datetime of the end of the term.
"end_at": "2014-05-16T05:00:00-04:00",
// The state of the term. Can be 'active' or 'deleted'.
"workflow_state": "active",
// Term date overrides for specific enrollment types
"overrides": {"StudentEnrollment":{"start_at":"2014-01-07T08:00:00-05:00","end_at":"2014-05-14T05:00:00-04:0"}},
// The number of courses in the term (available via include)
"course_count": 80
}
{
// a paginated list of all terms in the account
"enrollment_terms": []
}
// Configuration for the login discovery page
{
// Primary authentication provider buttons displayed prominently
"primary": null,
// Secondary authentication provider buttons displayed less prominently
"secondary": null,
// Whether the discovery page is enabled
"active": null
}
// A single authentication provider entry on the discovery page
{
// The ID of the authentication provider
"authentication_provider_id": 1,
// The display label for this provider button
"label": "Students",
// Icon key for this provider button
"icon": "google"
}
The day/time the term starts, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment
The day/time the term ends, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment
enrollment_term[end_at]
DateTime
The day/time the term ends. Accepts times in ISO 8601 format, e.g. 2015-01-10T18:48:00Z.
The day/time the term starts, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment
The day/time the term ends, overridden for the given enrollment type. enrollment_type can be one of StudentEnrollment, TeacherEnrollment, TaEnrollment, or DesignerEnrollment
override_sis_stickiness
boolean
Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness
term_name
string
If set, only returns terms that match the given search keyword. Search keyword is matched against term name.
The ID of an active authentication provider for this account.
discovery_page[secondary][][label]
string
The display label for this authentication provider button.
discovery_page[secondary][][icon]
string
Icon key for this authentication provider button.
Allowed values: description_html, params_html
parameters[course_id]
integer
The id of the course to report on. Note: this parameter has been listed to serve as an example and may not be valid for every report.
parameters[users]
boolean
If true, user data will be included. If false, user data will be omitted. Note: this parameter has been listed to serve as an example and may not be valid for every report.
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:
The "name" identifies the asset collection in human readable format.
The "guid" identifies the asset collection in machine readable format.
The "filters" object
The "filters" object stores the filtering expression for the asset collection. This stores facets and asset types which helps to filter to only the desired assets.
Here is a formal description about the filters object. For a practical explanation see the example below.
filters (object, required) - JSON API object for filters object containing various fields like: assetType and facets.
assetType (string) - The Asset type defines the Asset's structure and is setup by in Academic Benchmarks an Administrative User.
facets (array) - List of facets derived from the Asset Definition.
(object)
label (string) - Name of the facet. Derived from Asset Definition: data[n].attributes.properties[m].label
Asset filtering expression
Filtering an asset query by a "field" and different "values" in AB API looks like this:
With multiple fields it look like this:
Similar filters are created from the filters object. The left side of the query is the same. On the right side the expressions divided by the and are generated from the filters.facets list elements. The field_1 and field_2 are defined by field.id. The "values" are those items in the selectedFilters object which have the object-path defined in the facet.id. If facet.id == "a.b" then the values will be selectedFilters[i].a.b.
Example to build a "filter expression" from the "filters" object
Here is a filters object. Let's see how filter expression can be generated from it step-by-step:
The left side of the expression starts with filter[asset] =. There are two elements in the filters.facets array, so there will be two expressions on the right side. For example expressions expr_1 and expr_2. These are the basis of the filtering. The expr_1 is built up from filters.facets[0] and the expr_2 is built up from filters.facets[1].
Expressions are built up from a "field" and set of "values". The filter will give back those assets which have given the "values" on the given "field".
Let's find the "field" values. In the JSON object the "field" is defined by field.id.
Substitute these as "fields" into the filter expression.
Let's find the "values". The variables' names that are holding the "values" are defined by the facet.id. The "values" are those items in the selectedFilters object which have the object-path defined in the facet.id.
The variable for "values_1" is facet.id = "data.guid". Let's gather the values from selectedFilters.data.guid and generate the "values_1".
The variable for "values_2" is facet.id = "data.guid". Let's gather the values from selectedFilters.data.guid and generate the "values_2".
Finally substitute the "values" into the filter expression:
This example will filter only those assets which are in the grade: "Kindergarten" or "9th Grade" and are in the subject: "Mathematics".
Asset Collection
When there is a need to quickly identify and refer to a filtered collection of assets, the "Asset Collection" is what provides a solution. Asset Collection stores the filters object with a name and a guid as reference.
List All Asset Collections
To list Asset Collections the partner has access to, send a GET to the endpoint.
To find an Asset Collection by exact name, send a GET to the endpoint with the collection_name parameter. This gives back only the case sensitive exact match if there is any.
To search Asset Collections by name, send a GET to the endpoint with the search_collection_name parameter. This search uses case insensitive partial matching.
Create a new Asset Collection
To create an Asset Collection within the AB Connects system, you send a POST request to the endpoint. The body of the POST contains the Asset Collection definition in JSON format.
The response will be the same as a GET by GUID request for the created Asset Collection. See in the "Retrieving the Details of an Asset Collection".
Working with Assets Collection
Retrieving the Details of an Asset Collection
To get the Asset Collections you've created, call the endpoint with a GET while supplying the AB GUID for the Asset Collection. To retrieve the GUID, use the list and search functionality.
Modifying an Asset Collection
To update an Asset Collection, send a PATCH to the Asset Collection 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 can update the name, filters or advanced_search fields for the Asset Collection. You can update only one of these or all.
The response will contain the modified Asset Collection just as it would be in a GET by GUID request for the created Asset Collection. See in the "Retrieving Assets Collection".
Deleting an Asset Collection
To delete an Asset Collection you've created, send a DELETE the endpoint while supplying the AB GUID for the Asset Collection. If you have the name for the Asset Collection but not the AB GUID, see the section on searching for Asset Collections.
Authentication
In order to use the interactive Reference section, you will need to properly authenticate. If you do not have credentials, you can request a sandbox account. Alternatively, you can inquire about purchasing a license, or request access for your company's account, via AB Support.
Once you have your partner ID and key, you can create signatures and start to make calls to the production version of AB Connect. From a high level, the signature is an HMAC SHA-256 hash of a message constructed in a specific format. Use the partner key that is given to you by AB Support for the hash key. The message has one required field (expires - expressed in seconds since epoch) and three optional values: user, method and resource. The delimiter between the fields is a bare newline character (no carriage return) typically denoted as "\n". The generalized form of the message is:
<expires>[\nuser][\nmethod][\nresource]
Here are some example messages and their interpretation:
1508419888 - Access expires on October 19th 2017 at 1:31:28 PM ET. Note that expirations are expressed in Eastern time in the US.
1508419888\nbmarley - Same expiration time but the signature is only valid for Bob Marley's account. Note that if you supply a user, the user.id field must include the same value in the URL parameters.
1508419888\n\nGET - This signature can only be used for GET HTTP requests. Notice that the method is uppercase. This is a good approach when using AB Connect from public (or customer) facing web clients. It ensures that a hacker can't manipulate your Assets.
1508419888\n\nGET\nstandards - This signature can only be used for GET requests to standards. Notice that the resource is lowercase. If you have a web client that allows users to browse standards but you want to keep your Asset metadata profiles private, this will limit the scope accordingly.
NOTES:
Each field can have only one value, so you can't mix methods or support multiple endpoints. E.g. if you want to allow read access to both Standards and Topics, you'll need to create two signatures and use the appropriate signature for each call.
While the expires (auth.expires), signature (auth.signature) and optionally the user (user.id) are included in the URL parameters, the method and resource values are inferred from the actual call being made so there is no need to pass those as URL parameters.
Once you have calculated the signature, include the authentication parameters in the URL of your call to AB Connect. The general form of the parameters is:
&partner.id=<ID>&auth.signature=<signature generated above>&auth.expires=<signature expiry in seconds since epoch>
or if you are including a user ID:
&partner.id=<ID>&auth.signature=<signature generated above>&auth.expires=<signature expiry in seconds since epoch>&user.id=<user>
So if your partner ID is test_account and your key is ajk84Hjk93h59skaAJ8732 and you want to generate a read-only signature that expires on Wed Dec 06 2017 09:20:29 GMT-0500 (Eastern Standard Time)...
Your message would be: 1512570029\n\nGET
Your signature would be a base64 encoding of the HMAC SHA-256 hash of the message: Sdcfa9xgRAUzQnlLik5nKj1ntqdB85jFYyFCkNxwD/M=
URL encoding each parameter value and assembling the parameters together, the authentication portion of the URL would be: &partner.id=test_account&auth.signature=Sdcfa9xgRAUzQnlLik5nKj1ntqdB85jFYyFCkNxwD%2FM%3D&auth.expires=1512570029
You can use the following code examples as a starting point for constructing an authentication signature for use when calling AB Connect. Note that these examples do not necessarily follow coding best-practices - e.g. they do not have proper error handling in place. They are intended to be simple examples to show the concepts necessary to perform API authentication. Also note that these examples don't include any method or resource limiters in the signature.
Best Practices for Web Clients
Due to the nature of web clients, anything available to the client application can be accessed by the user. The user can view the source and use Inspect/Developer mode to access variable values, etc. For this reason, you need to be particularly careful with security measures. If you are accessing AB Connect directly from a web client, consider the following when creating your signatures:
Keep your partner key secret. Don't send it to the web client for any reason. If someone malicious gets a hold of your partner key, they can create any signature they want at any time they want and do damage to your Asset profiles. If you suspect your partner key has been compromised, contact AB Support and ask to have a new partner key issued.
Keeping your partner key secure means you need to generate the signature on the server side and embed the signature in the page as it is served to the client. Alternatively, you can create a service that generates signatures on request for your web clients. However, if you do that, you'll need to layer your own security model on top of that to ensure the web client making the request has permissions to access the AB Connect signature.
Make the life of the signature reasonably short. What is reasonable for your situation is up to you. Perhaps limit read capabilities to an hour and update (POST, PATCH, DELETE) to a few minutes. One thing to consider what is the user experience with the signature expires. Does the page force a re-load to gain a new token? Does it make an authenticated call to your server via AJAX to renew the signature? Does the user need to re-authenticate or do you trust a session cookie?
C#
See also the C# example project in the authentication folder of our .
Perl
See also the Perl example project in the authentication folder of our .
PHP
See also the PHP example project in the authentication folder of our .
Python2 (2.5 or Higher)
See also the Python2 example project in the authentication folder of our .
Python 3
See also the Python3 example project in the authentication folder of our .
VB.Net
See also the VB example project in the authentication folder of our .
Java
See also the Java example project in the authentication folder of our .
node.js
See also the NodeJS example project in the authentication folder of our .
Developer keys issued after Oct 2015 generate tokens with a 1 hour expiration. Applications must use to generate new access tokens.
is a protocol designed to let third-party applications authenticate to perform actions as a user, without getting the user's password. Canvas uses OAuth2 (specifically ) for authentication and authorization of the Canvas API. Additionally, Canvas uses OAuth2 for service authentication (as described in the ).
When appropriate, applications should store the token locally, rather than requesting a new token for the same user each time the user uses the application. If the token is deleted or expires, the application will get a 401 Unauthorized error from the API, in which case the application should perform the OAuth flow again to receive a new token. You can differentiate this 401 Unauthorized from other cases where the user simply does not have permission to access the resource by checking that the WWW-Authenticate header is set.
Storing a token is in many ways equivalent to storing the user's password, so tokens should be stored and used in a secure manner, including but not limited to:
Don't embed tokens in web pages.
Don't pass tokens or session IDs around in URLs.
Properly secure the database or other data store containing the tokens.
For web applications, practice proper techniques to avoid session attacks such as cross-site scripting, request forgery, replay attacks, etc.
For testing your application before you've implemented OAuth, the simplest option is to generate an access token on your user's profile page. Note that asking any other user to manually generate a token and enter it into your application is a violation of . Applications in use by multiple users MUST use OAuth to obtain tokens.
To manually generate a token for testing:
Click the "profile" link in the top right menu bar, or navigate to /profile
Under the "Approved Integrations" section, click the button to generate a new access token.
Once the token is generated, you cannot view it again, and you'll have to generate a new token if you forget it. Remember that access tokens are password equivalent, so keep it secret.
Your application can rely on canvas for a user's identity. During step 1 of the web application flow below, specify the optional scope parameter as scope=/auth/userinfo. When the user is asked to grant your application access in step 2 of the web application flow, they will also be given an option to remember their authorization. If they grant access and remember the authorization, Canvas will skip step 2 of the request flow for future requests.
Canvas will not give a token back as part of a userinfo request. It will only provide the current user's name and id.
If your application will be used by others, you will need to implement the full OAuth2 token request workflow, so that you can request an access token for each user of your application.
Performing the OAuth2 token request flow requires an application client ID and client secret. To obtain these application credentials, you will need to register your application. The client secret should never be shared.
For Canvas Cloud (hosted by Instructure), developer keys are .
NOTE for LTI providers: Since developer keys are scoped to the institution they are issued from, tool providers that serve multiple institutions should store and look up the correct developer key based on the launch parameters (eg. custom_canvas_api_domain) sent during the LTI launch.
For , you can and secret in the Site Admin account of your Canvas install.
A basic request looks like:
GET https://<canvas-install-url>/login/oauth2/auth?client_id=XXX&response_type=code&state=YYY&redirect_uri=https://example.com/oauth2response
See for details.
If the user accepts your request, Canvas redirects back to your request_uri with a specific query string, containing the OAuth2 response:
The app can then extract the code, and use it along with the client_id and client_secret to obtain the final access_key.
If your application passed a state parameter in step 1, it will be returned here in step 2 so that your app can tie the request and response together, whether the response was successful or an error occurred.
If the user doesn't accept the request for access, or if another error occurs, Canvas redirects back to your request_uri with an error parameter, rather than a code parameter, in the query string.
Canvas redirects to a page on canvas with a specific query string, containing parameters from the OAuth2 response:
/login/oauth2/auth?code=<code>
At this point the app should notice that the URL of the webview has changed to contain code=<code> somewhere in the query string. The app can then extract the code, and use it along with the client_id and client_secret to obtain the final access_key.
To get a new access token and refresh token, send a with the following parameters:
Parameters
Parameter
Value
Note that the once the code issued in step 2 is used in a POST request to this endpoint, it is invalidated and further requests for tokens with the same code will fail.
Once you have an OAuth access token, you can use it to make API requests. If possible, using the HTTP Authorization header is recommended.
OAuth2 Token sent in header:
Sending the access token in the query string or POST parameters is also supported, but discouraged as it increases the chances of the token being logged or leaked in transit.
OAuth2 Token sent in query string:
Access tokens have a 1 hour lifespan. When the refresh flow is taken, Canvas will update the access token to a new value, reset the expiration timer, and return the new access token as part of the response. When refreshing tokens the user will not be asked to authorize the application again.
To refresh the access token, send a with the following parameters:
Parameters
Parameter
Value
The response to this request will not contain a new refresh token; the same refresh token is to be reused.
To logout, simply send a
LTI Advantage services, such as and , require use of a client credentials grant flow for request authentication. This workflow is best summarized on the IMS Security Framework (specifically ).
Our goal here is to highlight some nuances that might help you access these services in Canvas, rather than describing the specification in detail.
Before the client_credentials grant flow can be achieved, an . During developer key configuration, a public JWK can either be configured statically or can be dynamically rotated by providing JWKs by a URL that Canvas can reach. Tools may also use a previously issued client_credentials token to . The JWK must include an alg and use.
Example JWK
Once the developer key is configured and turned on, your tool can . This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in .
Once you have an access token, you can use it to make LTI service requests. The access token must be included as a Bearer token in the Authorization header:
Access tokens only work in the context of where a tool has been deployed. Tools can only access line items that are associated with their tool.
The following endpoints are currently supported:
Names and Role Provisioning Services
Assignment and Grade Services
This documentation is generated directly from the Canvas LMS source code, available .
Manage Canvas API Keys, used for OAuth access to this API. See the OAuth access docs for usage of these keys. Note that DeveloperKeys are also (currently) used for LTI 1.3 registration and OIDC access, but this endpoint deals with Canvas API keys. See for details.
Create a new Canvas API key. Creating an LTI 1.3 registration is not supported here and should be done via the LTI Registration API.
Request Parameters:
Parameter
Type
Description
Returns a object.
PUT /api/v1/developer_keys/:id
Scope:url:PUT|/api/v1/developer_keys/:id
Update an existing Canvas API key. Updating an LTI 1.3 registration is not supported here and should be done via the LTI Registration API.
Request Parameters:
Parameter
Type
Description
Returns a object.
DELETE /api/v1/developer_keys/:id
Scope:url:DELETE|/api/v1/developer_keys/:id
Delete an existing Canvas API key. Deleting an LTI 1.3 registration should be done via the LTI Registration API.
Returns a object.
This documentation is generated directly from the Canvas LMS source code, available .
Blueprint Courses
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Blueprint Courses API
Configure blueprint courses
Analytics
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Analytics API
API for retrieving the data exposed in Canvas Analytics
OAuth2 Endpoints
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
OAuth2 Endpoints
Using AB Connect's Embeddable Widgets
Overview
In continuing efforts to make the process of working with academic Standards easy and efficient, we have begun to create plug-able widgets that can be used directly in apps created by our partners. The widgets are designed to enable our partners to offer capabilities within their apps with only a few lines of code. We will continue to expand the capabilities of the widgets as well as add to the list of supported widgets over time.
Our initial offering is a widget that enables the end user to browse for and select Standards. We will continue to expand the capabilities to support faceted and full text search as well as search-by-number.
filter[assets]=(alignments.id eq '6B29DCD6-29EB-11D8-9C6E-A97B3BAEC73A')
filter[assets]=(alignments.id in ('6B29DCD6-29EB-11D8-9C6E-A97B3BAEC73A','6DF95514-36D9-11E6-B844-14D399AB8BA3'))
{
// the ID of the course pace
"id": 5,
// the ID of the course
"course_id": 5,
// the ID of the user for this course pace
"user_id": 10,
// the state of the course pace
"workflow_state": "active",
// boolean value depending on exclude weekends setting
"exclude_weekends": true,
// array of strings representing the days of the work week
"selected_days_to_skip": [fri, sat],
// set if the end date is set from course
"hard_end_dates": true,
// date when course pace is created
"created_at": "2013-01-23T23:59:00-07:00",
// course end date
"end_date": "2013-01-23T23:59:00-07:00",
// date when course pace is updated
"updated_at": "2013-01-23T23:59:00-07:00",
// date when course pace is published
"published_at": "2013-01-23T23:59:00-07:00",
// the root account ID for this course pace
"root_account_id": 10,
// course start date
"start_date": "2013-01-23T23:59:00-07:00",
// list of modules and items for this course pace
"modules": null,
// progress of pace publishing
"progress": null
}
{
// the ID of the module
"id": 5,
// the name of the module
"name": "Module 1",
// the position of the module
"position": 5,
// list of module items
"items": null,
// the ID of the context for this course pace
"context_id": 10,
// The given context for the course pace
"context_type": "Course"
}
{
// the ID of the module item
"id": 5,
// the duration of the module item
"duration": 5,
// the course pace id of the module item
"course_pace_id": 5,
// the root account id of the module item
"root_account_id": 5,
// the module item id of the module item
"module_item_id": 5,
// The title of the item assignment
"assignment_title": "Assignment 9",
// The points of the item
"points_possible": 10.0,
// The link of the item assignment
"assignment_link": "/courses/105/modules/items/264",
// the current position of the module item
"position": 5,
// The module item type of the item assignment
"module_item_type": "Assignment",
// published boolean value for course pace
"published": true
}
{
// the ID of the Progress object
"id": 1,
// the context owning the job.
"context_id": 1,
"context_type": "Account",
// the id of the user who started the job
"user_id": 123,
// the type of operation
"tag": "course_batch_update",
// percent completed
"completion": 100,
// the state of the job one of 'queued', 'running', 'completed', 'failed'
"workflow_state": "completed",
// the time the job was created
"created_at": "2013-01-15T15:00:00Z",
// the time the job was last updated
"updated_at": "2013-01-15T15:04:00Z",
// optional details about the job
"message": "17 courses processed",
// optional results of the job. omitted when job is still pending
"results": {"id":"123"},
// url where a progress update can be retrieved
"url": "https://canvas.example.edu/api/v1/progress/1"
}
filter[asset] = education_levels.grades in ("F1F9FA12-3B53-11E0-A421-F4B24952E9DF", "ABBAABBA-ACDC-ACDC-B042-495E9DFF4B22") and disciplines.subjects.ids in ("495E9DFF-3B53-11E0-B042-C4B222F1FB2F")
end_date_context
string
End date context (course, section, hupothetical)
start_date
Datetime
Start date of the course pace
start_date_context
string
Start date context (course, section, hupothetical)
exclude_weekends
boolean
Course pace dates excludes weekends if true
selected_days_to_skip
string
Array
Course pace dates excludes weekends if true
hard_end_dates
boolean
Course pace uess hard end dates if true
workflow_state
string
The state of the course pace
course_pace_module_item_attributes[]
string
Module Items attributes
context_id
integer
Pace Context ID
context_type
string
Pace Context Type (Course, Section, User)
end_date
Datetime
End date of the course pace
exclude_weekends
boolean
Course pace dates excludes weekends if true
selected_days_to_skip
string
Array
Course pace dates excludes weekends if true
hard_end_dates
boolean
Course pace uess hard end dates if true
workflow_state
string
The state of the course pace
course_pace_module_item_attributes[]
string
Module Items attributes
If you specify a resource, you must specify a method. Allowing "all methods" on one endpoint is not currently supported. So, for example, your message can not look like 1508419888\n\n\nassets.
Limit the method to the minimum required capabilities. Most web clients will only need read access (e.g. if you are offering the user a Standards or Asset browser). If you need to change permissions, consider creating a separate, short-lived signature for those situations.
Returns page view hits summed across all courses in the department. Two groupings of these counts are returned; one by day (by_date), the other by category (by_category). The possible categories are announcements, assignments, collaborations, conferences, discussions, files, general, grades, groups, modules, other, pages, and quizzes.
This and the other department-level endpoints have three variations which all return the same style of data but for different subsets of courses. All share the prefix /api/v1/accounts/<account_id>/analytics. The possible suffixes are:
Courses not yet offered or which have been deleted are never included.
/current and /completed are intended for use when the account has only one term. /terms/<term_id> is intended for use when the account has multiple terms.
Returns the distribution of grades for students in courses in the department. Each data point is one student’s current grade in one course; if a student is in multiple courses, he contributes one value per course, but if he’s enrolled multiple times in the same course (e.g. a lecture section and a lab section), he only constributes on value for that course.
Grades are binned to the nearest integer score; anomalous grades outside the 0 to 100 range are ignored. The raw counts are returned, not yet normalized by the total count.
Shares the same variations on endpoint as the participation data.
Returns page view hits and participation numbers grouped by day through the entire history of the course. Page views is returned as a hash, where the hash keys are dates in the format “YYYY-MM-DD”. The page_views result set includes page views broken out by access category. Participations is returned as an array of dates in the format “YYYY-MM-DD”.
Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown, and a breakdown of on-time/late status of homework submissions.
Request Parameters:
Parameter
Type
Description
async
boolean
If async is true, then the course_assignments call can happen asynch- ronously and MAY return a response containing a progress_url key instead of an assignments array. If it does, then it is the caller’s responsibility to poll the API again to see if the progress is complete. If the data is ready (possibly even on the first async call) then it will be passed back normally, as documented in the example response.
Returns a summary of per-user access information for all students in a course. This includes total page views, total participations, and a breakdown of on-time/late status for all homework submissions in the course.
Each student’s summary also includes the maximum number of page views and participations by any student in the course, which may be useful for some visualizations (since determining maximums client side can be tricky with pagination).
Request Parameters:
Parameter
Type
Description
sort_column
string
The order results in which results are returned. Defaults to “name”.
Returns page view hits grouped by hour, and participation details through the entire history of the course.
page_views are returned as a hash, where the keys are iso8601 dates, bucketed by the hour. participations are returned as an array of hashes, sorted oldest to newest.
Returns a list of assignments for the course sorted by due date. For each assignment returns basic assignment information, the grade breakdown (including the student’s actual grade), and the basic submission information for the student’s submission if it exists.
Returns messaging “hits” grouped by day through the entire history of the course. Returns a hash containing the number of instructor-to-student messages, and student-to-instructor messages, where the hash keys are dates in the format “YYYY-MM-DD”. Message hits include Conversation messages and comments on homework submissions.
Example Request:
Example Response:
This documentation is generated directly from the Canvas LMS source code, available on Github.
using System;
using System.IO;
using System.Net;
using System.Security.Cryptography;
using System.Text;
class Program
{
static void Main(string[] args)
{
var partnerID = "public"; // ID provided by AB.
var partnerKey = "2jfaWErgt2+o48gsk302kd"; // Key provided by AB.
var userID = "Bob"; // Optional. Partner defined string. Provides access only for queries with this `user.id`.
// Seconds since epoch. Example is 24 hours.
var expires = (long)Math.Floor(
(DateTime.UtcNow.AddHours(24) - new DateTime(1970, 1, 1, 0, 0, 0)).TotalSeconds
);
var message = string.Format("{0}\n{1}", expires, userID);
var keyBytes = Encoding.UTF8.GetBytes(partnerKey);
var messageBytes = Encoding.UTF8.GetBytes(message);
string signature;
using (var hmac = new HMACSHA256(keyBytes))
{
signature = Convert.ToBase64String(hmac.ComputeHash(messageBytes));
}
var requestBuilder = new UriBuilder("https://api.abconnect.instructure.com/rest/v4.1/standards");
// user.id is optional
requestBuilder.Query = string.Format(
"partner.id={0}&auth.signature={1}&auth.expires={2}&user.id={3}",
WebUtility.UrlEncode(partnerID),
WebUtility.UrlEncode(signature),
expires,
WebUtility.UrlEncode(userID)
);
var request = WebRequest.Create(requestBuilder.Uri);
Console.WriteLine(new StreamReader(request.GetResponse().GetResponseStream()).ReadToEnd());
}
}
#!/usr/bin/perl
use strict;
use Digest::SHA qw(hmac_sha256_base64);
use LWP::UserAgent;
my $partner_id = 'public'; # ID provided by AB.
my $partner_key = '2jfaWErgt2+o48gsk302kd'; # Key provided by AB.
my $expires = time() + 86400; # Seconds since epoch. Example is 24 hours.
my $user_id = 'Bob'; # Optional. Partner defined string. Provides access only for queries with this `user.id`.
my $message = "$expires\n$user_id";
my $signature = hmac_sha256_base64($message, $partner_key);
my $uri = URI->new();
$uri->scheme('https');
$uri->host('api.abconnect.instructure.com');
$uri->port(443);
$uri->path('rest/v4.1/standards');
# user.id is optional
$uri->query_form(
'partner.id' => $partner_id,
'auth.signature' => $signature,
'auth.expires' => $expires,
'user.id' => $user_id
);
my $req = HTTP::Request->new(GET => $uri);
my $ua = LWP::UserAgent->new();
my $response = $ua->request($req);
print 'response code = '.$response->{_rc}."\n";
if ($response->{_rc} && ($response->{_rc} == 200)) {
if ($response->{_content}) {
print $response->{_content};
}
}
<!DOCTYPE html>
<HTML>
<HEAD>
</HEAD>
<BODY>
<?php
$partnerID = 'public'; // ID provided by AB.
$partnerKey = '2jfaWErgt2+o48gsk302kd'; // Key provided by AB.
$authExpires = time() + 3600; // Seconds since epoch. Example is 1 hour. Keep this shorter due to web exposure.
$userID = 'Bob'; // Optional. Partner defined string. Provides access only for queries with this `user.id`.
$url = 'https://api.abconnect.instructure.com/rest/v4.1/standards?';
$url .= 'partner.id=' . $partnerID;
// "GET" results read only signature to minimize security risks with web client exposure.
$message = $authExpires . "\n" . $userID . "\n" . "GET";
$sig = urlencode(base64_encode(hash_hmac('sha256', $message, $partnerKey, true))); // build the signature with the key
$url .= '&auth.signature=' . $sig;
$url .= '&auth.expires=' . $authExpires;
if ($url) {
$url .= '&user.id=' . $userID;
}
print '<H3>Generated Request URL</H3>';
print '<P>' . $url . '</P><BR />';
$response = file_get_contents($url);
print '<H3>JSON Response</H3>';
print '<P>' . $response . '</P>';
?>
</BODY>
</HTML>
import time
import hashlib
import hmac
import base64
import urllib
partner_id = 'public' # ID provided by AB.
partner_key = '2jfaWErgt2+o48gsk302kd' # Key provided by AB.
expires = str(int(time.time() + 86400)) # Seconds since epoch. Example expires in 24 hours.
user_id = 'Bob' # Optional. Partner defined string. Provides access only for queries with this `user.id`.
message = expires + "\n" + user_id
digest = hmac.new(partner_key.encode(), message.encode(), digestmod=hashlib.sha256).digest()
signature = base64.b64encode(digest).decode()
encoded_sig = urllib.quote_plus(signature)
# user.id is optional
parms = 'partner.id=' + partner_id + \
'&auth.signature=' + encoded_sig + \
'&auth.expires=' + expires + \
'&user.id=' + user_id
result = urllib.urlopen('https://api.abconnect.instructure.com/rest/v4.1/standards?' + parms).read()
print result
import time
import hashlib
import hmac
import base64
import urllib.request
partner_id = 'public' # ID provided by AB.
partner_key = '2jfaWErgt2+o48gsk302kd' # Key provided by AB.
expires = str(int(time.time() + 86400)) # Seconds since epoch. Example expires in 24 hours.
user_id = 'Bob' # Optional. Partner defined string. Provides access only for queries with this `user.id`.
message = expires + "\n" + user_id
digest = hmac.new(partner_key.encode(), message.encode(), digestmod=hashlib.sha256).digest()
signature = base64.b64encode(digest).decode()
encoded_sig = urllib.parse.quote_plus(signature)
# user.id is optional
parms = 'partner.id=' + partner_id + \
'&auth.signature=' + encoded_sig + \
'&auth.expires=' + expires + \
'&user.id=' + user_id
result = urllib.request.urlopen('https://api.abconnect.instructure.com/rest/v4.1/standards?' + parms).read()
print (result)
Imports System.Security.Cryptography
Imports System.Text
Imports System.Net
Imports System.IO
Module AuthModule
Sub Main()
Dim PartnerId As String = "public" ' ID provided by AB.
Dim PartnerKey As String = "2jfaWErgt2+o48gsk302kd" ' Key provided by AB.
Dim UserId As String = "Bob" ' Optional. Partner defined string. Provides access only for queries with this `user.id`.
' Seconds since epoch. Example is 24 hours.
Dim Expires = Math.Floor(
(DateTime.UtcNow.AddHours(24) - New DateTime(1970, 1, 1, 0, 0, 0)).TotalSeconds
)
Dim Message = Expires & vbLf & UserId
Dim KeyBytes() As Byte = Encoding.UTF8.GetBytes(PartnerKey)
Dim MessageBytes() As Byte = Encoding.UTF8.GetBytes(Message)
Dim Signature As String
Using myHMACSHA256 As New HMACSHA256(KeyBytes)
Signature = Convert.ToBase64String(myHMACSHA256.ComputeHash(MessageBytes))
End Using
Dim RequestBuilder As New UriBuilder("https://api.abconnect.instructure.com/rest/v4.1/standards")
' user.id is optional
RequestBuilder.Query = String.Format(
"partner.id={0}&auth.signature={1}&auth.expires={2}&user.id={3}",
WebUtility.UrlEncode(PartnerId),
WebUtility.UrlEncode(Signature),
Expires,
WebUtility.UrlEncode(UserId)
)
Dim Request = WebRequest.Create(RequestBuilder.Uri)
Dim Response As WebResponse = Request.GetResponse()
Dim ReceiveStream As Stream = Response.GetResponseStream()
Dim Encode As Encoding = Encoding.GetEncoding("utf-8")
Dim ReadStream As New StreamReader(ReceiveStream, Encode)
Dim ReadBuffer(256) As [Char]
Dim Count As Integer = ReadStream.Read(ReadBuffer, 0, 256)
While Count > 0
Dim StringData As New [String](ReadBuffer, 0, Count)
Console.Write(StringData)
Count = ReadStream.Read(ReadBuffer, 0, 256)
End While
Console.WriteLine("")
End Sub
End Module
package AuthExample;
import java.io.BufferedReader;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.net.URL;
import java.net.URLEncoder;
import java.util.Base64;
import java.util.Calendar;
import java.util.TimeZone;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import javax.net.ssl.HttpsURLConnection;
public class program {
public static void main(String[] args) {
String partnerID = "public"; // ID provided by AB.
String partnerKey = "2jfaWErgt2+o48gsk302kd"; // Key provided by AB.
String userID = "Bob"; // Optional. Partner defined string. Provides access only for queries with this `user.id`.
// Seconds since epoch. Example is 24 hours.
Calendar cal = Calendar.getInstance(TimeZone.getTimeZone("GMT"));
long expires = (long)Math.floor(cal.getTimeInMillis() / 1000) + 60*60*24;
String message = String.format("%d\n%s", expires, userID); // format message for signature
HttpsURLConnection connection = null;
try {
//
// generate signature and base64 encode it
//
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(partnerKey.getBytes("UTF-8"), "HmacSHA256");
sha256_HMAC.init(secret_key);
byte[] hmacBytes = sha256_HMAC.doFinal(message.getBytes("UTF8"));
String signature = Base64.getEncoder().encodeToString(hmacBytes);
//
// pack the signature and other auth parameters in URL
//
String targetURL = String.format(
"https://api.abconnect.instructure.com/rest/v4.1/standards?partner.id=%s&auth.signature=%s&auth.expires=%d&user.id=%s",
URLEncoder.encode(partnerID, "UTF-8"),
URLEncoder.encode(signature, "UTF-8"),
expires,
URLEncoder.encode(userID, "UTF-8")
);
//
//Create connection
//
URL url = new URL(targetURL);
connection = (HttpsURLConnection) url.openConnection();
//
// Get Response
//
InputStream is = connection.getInputStream();
BufferedReader rd = new BufferedReader(new InputStreamReader(is));
String line;
while ((line = rd.readLine()) != null) {
System.out.println(line);
}
rd.close();
} catch (Exception e) {
e.printStackTrace();
System.exit(-1);
} finally {
if (connection != null) {
connection.disconnect();
}
}
}
}
#!/usr/bin/env node
var partner_id = 'public' // ID provided by AB.
var partner_key = '2jfaWErgt2+o48gsk302kd' // Key provided by AB.
var expires = Math.floor(Date.now() / 1000) + 86400; // Seconds since epoch. Example expires in 24 hours.
var user_id = 'Bob' // Optional. Partner defined string. Provides access only for queries with this `user.id`.
//
// Build the signature
//
var message = '' + expires;
if (user_id) {
message += "\n" + user_id;
}
var crypto = require('crypto');
var signature = crypto.createHmac('SHA256', partner_key).update(message).digest('base64')
//
// package the signature, expiration, etc. into a URL encoded query string fragment
//
var queryString = '&partner.id=' + encodeURIComponent(partner_id) + '&auth.signature=' + encodeURIComponent(signature) + '&auth.expires=' + encodeURIComponent(expires);
if (user_id) {
queryString += '&user.id=' + encodeURIComponent(user_id);
}
console.log("Authentication parameters: " + queryString);
var requester = require('sync-request');
var response;
var body;
try {
response = requester('GET', 'https://api.abconnect.instructure.com/rest/v4.1/standards?' + queryString);
body = response.getBody('utf-8');
} catch (e) {
console.log('' + e);
}
if (response) console.log("Response code: " + response.statusCode);
if (body) console.log("Response body:\n" + body);
// a Canvas API key (or LTI 1.3 registration)
{
// The Canvas ID of the DeveloperKey object
"id": 1,
// The display name
"name": "Test Key",
// Timestamp of the key's creation
"created_at": "2025-05-30T17:09:18Z",
// Timestamp of the key's last update
"updated_at": "2025-05-30T17:09:18Z",
// The state of the key
"workflow_state": "active",
// True if key represents an LTI 1.3 Registration. False for Canvas API keys
"is_lti_key": false,
// Contact email configured for key
"email": "[email protected]",
// URL for a small icon to display in key list
"icon_url": "https://example.com/icon.png",
// User-provided notes about key
"notes": "this key is for testing",
// User-specified code representing the vendor that uses the key
"vendor_code": "Google",
// The name of the account that owns the key
"account_name": "Test Account",
// True for all keys except Site Admin-level keys, which default to false.
// Controls visibility in the Inherited tab.
"visible": true,
// List of API endpoints key is allowed to access (API keys), or LTI 1.3 scopes
// (LTI keys)
"scopes": ["url:GET|/api/v1/accounts"],
// Deprecated in favor of redirect_uris. Do not use.
"redirect_uri": "no",
// List of URLs used during OAuth2 flow to validate given redirect URI (API
// keys), or to redirect to after login (LTI keys)
"redirect_uris": ["https://mytool.com/oauth2/redirect", "https://mytool.com/1_3/launch"],
// (API keys only) The number of active access tokens associated with the key
"access_token_count": 42,
// (API keys only) The last time an access token for this key was used in an API
// request
"last_used_at": "2025-05-30T17:09:18Z",
// (API keys only) If true, key is only usable in non-production environments
// (test, beta). Avoids problems with beta refresh.
"test_cluster_only": false,
// (API keys only) If true, allows `includes` parameters in API requests that
// match the scopes of this key
"allow_includes": true,
// (API keys only) If true, then token requests with this key must include
// scopes
"require_scopes": false,
// (API keys only) Used in OAuth2 client credentials flow to specify the
// audience for the access token
"client_credentials_audience": "external",
// (API keys only) The client secret used in the OAuth authorization_code flow.
"api_key": "sd45fg64....",
// (LTI keys only) The Canvas-style tool configuration for this key.
"tool_configuration": {"type":"Lti::ToolConfiguration"},
// (LTI keys only) The tool's public JWK in JSON format. Discouraged in favor of
// a url hosting a JWK set.
"public_jwk": {"e":"AQAB","etc":"etc"},
// (LTI keys only) The tool-hosted URL containing its public JWK keyset. Canvas
// may cache JWKs up to 5 minutes.
"public_jwk_url": "https://mytool.com/1_3/jwks",
// (LTI keys only) The LTI IMS Registration object for this key, if key was
// created via Dynamic Registration.
"lti_registration": {"type":"TODO Lti::IMS::Registration"},
// (LTI keys only) Returns true if key was created via Dynamic Registration.
"is_lti_registration": false,
// Unused.
"user_name": "",
// Unused.
"user_id": "",
// Correlates an API key to a product configuration.
"unified_tool_id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
}
* /current: includes all available courses in the default term
* /completed: includes all concluded courses in the default term
* /terms/<term_id>: includes all available or concluded courses in the
given term.
field (object) - The field object for the property. Derived from Asset Definition: data[n].attributes.properties[m].field.
name (string) - The API-recognized name for the entity you are filtering by. This is the property you would use when asking for facets.
id (string) - API identifier for the field which uniquely identifies the entity being filtered by. This is the property you would use when constructing your filter statement as the key field.
facet (object) - The facets object for the property. Derived from Asset Definition: data.[n].attributes.properties.[m].facet
name (string) - The API Identifier for the human-readable property in the facets response.
id (GUID) - The API Identifier for the entity-unique property in the facets response. This is the property you would use when constructing your filter statement and thus must correspond with the values in this entity’s field.id.
selectedFilters (array) - The list of selected values for the queries.
(object) - This objects holds the elements to which the facid.id refers.
data (object) - The object details for this facet item. See the definition of the object for the specific facet for details, but they all have at least the descr and guid.
descr (string) - Facet value text.
guid (GUID) - Facet value GUID.
code (string) - Facet value code name.
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[asset_collections]stringOptional
comma separated list of field names
filter[asset_collections]stringOptional
an ODATA-like query string used to filter
sort[asset_collections]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
guidstringOptional
namestringOptional
Other propertiesanyOptional
Other propertiesanyOptional
400
Bad Request
application/json
401
Authentication Error
application/json
get
/asset_collections
post
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
namestringRequired
filtersobjectRequired
advanced_searchobjectOptional
Responses
201
Created
application/json
400
Bad Request
application/json
401
Authentication Error
application/json
409
Conflict
application/json
422
Unprocessable content
application/json
post
/asset_collections
get
Path parameters
guidstringRequired
guid of specified asset collection
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[asset_collections]stringOptional
comma separated list of field names
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
For native applications, take advantage of user keychain stores and other operating system functionality for securely storing passwords.
code
code from canvas
replace_tokens
(optional) If this option is set to `1`, existing access tokens issued for this developer key/secret will be destroyed and replaced with the new token that is returned from this request
If a redirect_uri was passed to the initial request in step 1, the same redirect_uri must be given here.
refresh_token from initial access_token request
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
countnumberOptional
facetstringOptional
descrstringOptional
codestringOptional
guidstringOptional
countnumberOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
idstringOptional
Synonym for our GUID field required by the JSON API standard.
prediction_algorithmnumberOptional
The version number of the algorithm used by this Asset to predict relationships. Assets created and managed through AB Connect v3 or earlier versions of the AB Aligned user interface will be on prediction algorithm version 2. AB Connect v4.1 and beyond use algorithm version 3. If you modify a relationship on an Asset that is using algorithm 2 via AB Connect v4.1, the system will automatically convert the Asset prediction algorithm to 3 and may have an impact on predicted alignments. You may choose to give your end user a warning to this affect and have them confirm their actions before modifying the relationship.
date_modified_utcstringOptional
The most recent modification date of this Asset in UTC.
client_idstringOptional
Your ID for the Asset. The combination client_id and asset_type must be unique.
guidstringOptional
AB GUID for this Asset.
stringOptional
or
numberOptional
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
The date of the most recent modification of a relationship between a Standard and this Asset in UTC.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
asset_typestringOptional
The type of the Asset. The Asset type define's the Asset's structure and is setup by in Academic Benchmarks by AB Support.
typestring · enumOptional
Literal "assets" - JSON API requirement.
Possible values:
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
or
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
or
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
or
typestring · enumOptional
Literal "providers" - JSON API requirement.
Possible values:
idstringOptional
Synonym for our GUID field required by the JSON API standard.
Using ‘default’ as the template_id should suffice for the current implmentation (as there should be only one template per course). However, using specific template ids may become necessary in the future
Send a list of course ids to add or remove new associations for the template. Cannot add courses that do not belong to the blueprint course’s account. Also cannot add other blueprint courses or courses that already have an association with another blueprint course.
After associating new courses, start a sync to populate their contents from the blueprint.
Retrieve a list of learning objects that have changed since the last blueprint sync operation. If no syncs have been completed, a ChangeRecord with a change_type of initial_sync is returned.
Shows a paginated list of migrations for the template, starting with the most recent. This endpoint can be called on a blueprint course. See also the associated course side.
Show the changes that were propagated in a blueprint migration. This endpoint can be called on a blueprint course. See also the associated course side.
Shows a paginated list of migrations imported into a course associated with a blueprint, starting with the most recent. See also the blueprint course side.
Use ‘default’ as the subscription_id to use the currently active blueprint subscription.
GET https://<canvas-install-url>/login/oauth2/auth?client_id=XXX&response_type=code&redirect_uri=https://example.com/oauth_complete&state=YYY&scope=<value_1>%20<value_2>%20<value_n>
Parameters
Parameter
Required
Description
client_id
Required
The client id for your registered application.
response_type
Required
The type of OAuth2 response requested. The only currently supported value is code.
POST login/oauth2/token
See Section 4.1.3 of the OAuth2 RFC for more information about this process.
POST /login/oauth2/token
Parameters
Parameter
Required
Description
grant_type
Required
Values currently supported: "authorization_code", "refresh_token", and "client_credentials".
client_id
Required for grant_types: authorization_code, refresh_token
The client id for your registered application.
Canvas API example responses
For grant_type of code or refresh_token:
Parameter
Description
access_token
The OAuth2 Canvas API access token.
token_type
The type of token that is returned.
user
A JSON object of canvas user id and user name.
refresh_token
When using grant_type=code (ex: for Canvas API access):
When using grant_type=refresh_token, the response will not contain a new refresh token since the same refresh token can be used multiple times:
If scope=/auth/userinfo was specified in the GET login/oauth2/auth request (ex: when using Canvas as an authentication service) then the response that results from POST login/oauth2/token would be:
This request must be signed by an RSA256 private key with a public key that is configured on the developer key as described in Step 1: Developer Key Setup.
Below is an example of the decoded client_assertion JWT in the above request:
NOTE:
the value of the sub claim should match the client_id of the developer key in Canvas.
the value of the aud claim should contain either the domain of the Canvas account where the desired data resides, or the domain of the LTI 1.3 OIDC Auth endpoint, as described here.
if the public key defined on the developer key is a JWK set (specified by an URL) the kid (key ID) value in the signed JWT header must match one of the public keys returned by the public key URL.
Example Response
Parameter
Description
access_token
The OAuth2 client_credentials access token.
token_type
The type of token that is returned.
expires_in
Seconds until the access token expires.
scope
DELETE login/oauth2/token
If your application supports logout functionality, you can revoke your own access token. This is useful for security reasons, as well as removing your application from the list of tokens on the user's profile page. Simply make an authenticated request to the following endpoint by including an Authorization header or providing the access_token as a request parameter.
DELETE /login/oauth2/token
Parameters
Parameter
Required
Description
expire_sessions
Optional
Set this to '1' if you want to end all of the user's Canvas web sessions. Without this argument, the endpoint will leave web sessions intact.
Additionally, if the user logged in to Canvas via a delegated authentication provider, and the provider supports Single Log Out functionality, the response will contain a forward_url key. If you are still in control of the user's browsing session, it is recommended to then redirect them to this URL, in order to also log them out from where their session originated. Beware that it is unlikely that control will be returned to your application after this redirect.
Example responses
GET login/session_token
If your application needs to begin a normal web session in order to access features not supported via API (such as quiz taking), you can use your API access token in order to get a time-limited URL that can be fed to a browser or web view to begin a new web session.
GET /login/session_token
Parameters
Parameter
Required
Description
return_to
Optional
An optional URL to begin the web session at. Otherwise the user will be sent to the dashboard.
Example responses
This documentation is generated directly from the Canvas LMS source code, available on Github.
Instructure's Academic Benchmarks widgets are hosted on Amazon's Content Delivery Network (CDN) to ensure high availability and responsiveness.
Standards Browser Integration
Integration
The app is built on jQuery and completely embeds all requirements directly within the one package to ensure smooth integration. To plug the widget into your app, start by including the script into your HTML file:
The required version of jQuery is encapsulated within the widget JavaScript to avoid version dependency issues but the order in which your app loads the various libraries matters. If you use jQuery, you should always load jQuery before the AB Connect widgets. We've bundled a version of jQuery in such a way as not to interfere with other versions that may be included on the page. To ensure the smoothest integration possible, the widget will handle the encapsulated jQuery in the following manor:
If jQuery was loaded into the page before the widgets, then the widgets will be installed into it but the widgets will use the encapsulated version of jQuery internally.
If jQuery is not loaded at all, then the encapsulated version of jQuery (and widgets) will be installed into the page. (version 2.2.4)
If jQuery is loaded after the widgets, then the version of jQuery (and widgets) installed by AB Connect will be rendered inaccessible.
Adding the Widget to Your Page
Once the script is included, create a div to hold the widget. Note that the widget was designed for a minimum size of 800 x 600 px. If it is given more space than that, it will expand to take advantage of it. You can give the div any name/class/tag you like.
The config object can be used to define the behavior of the widget as well as how it interacts with your app.
Configuration
The configuration object you include in the widget initiation can help control the behavior of the widget. This section describes the properties of the configuration object and how they are used to control the widget.
uiEntityState - This is an object property that defines the initial values of elements in the UI as well as their visibility. Each property of the uiEntityState object contains an optional flag (named "show") indicating whether that element is visible and a value property indicating the initial value(s) of the element. If the "show" property is left out, the default is true. If the value property is left out, no initial selection is made. If the element property is not included, the element is visible with no initial selection. Properties:
authority - Indicates the drop-down listing the authorities available for browsing. The value property is the GUID of the initial authority selection.
publication - Indicates the drop-down listing the publications available for browsing. The value property is the GUID of the initial publication selection.
document - Indicates the drop-down listing the documents available for browsing. The value property is the GUID of the initial document selection.
E.g.:
would pre-select the Common Core Math Standards and hide the lists so the user couldn't change the selection.
selectMode - This is a property indicating whether the browser is in single select mode (single - the default) or multiple select mode (multiple). If false, the user can select multiple Standards at a time. Note that the selection is cleared when the user changes facet filtering, does a search or changes document. It is the responsibility of the parent app to offer a mechanism to build and manage a persistent list of Standards if appropriate for the app.
enableDoubleClick - This is a Boolean property indicating whether the browser supports double clicks (true). Default: false.
showAssetCount - This is a Boolean property indicating whether the browser should show a badge indicating the number of Assets that are related to the Standard. This can be used in situations where the parent app is using the Standards Browser as a first step in helping the user search for related Assets. Note that this capability requires that your organization stores your content metadata profile as Assets in AB Connect. The default is false.
assetCountFilter - This is a string property that is added to the AB Connect query that is used to retrieve the Asset count when the showAssetCount is true. By default, the widget counts any Assets that are owned by your account and are related to the Standard in question. However, you can pass a query string that is then appended to the query with an AND operator to further limit the query. E.g. you may want to further limit the results to a particular type of Asset or Assets of a particular media type. This property is optional and only used if showAssetCount is true.
authCredentials - This is an object property containing the authorization credentials. See the AB Connect for details.
ID - Your partner ID
signature -signature generated from your partner key and the expires value
onStandardSelect - An event handler defined by your app to handle selection events for Standards. The signature of the function must be function (event, GUID). The GUID of the Standard that was selected is the second parameter. This property is optional. Alternatively, you can register your event handlers directly via jQuery.
onStandardDoubleClick - An event handler defined by your app to handle double-click events for Standards. The signature of the function must be function (event, GUID). The GUID of the Standard that was clicked is the second parameter. This property is optional.
onStandardDeselect - An event handler defined by your app to handle deselection events for Standards. The signature of the function must be function (event, GUID). The GUID of the Standard that was deselected is the second parameter. Note that this event will fire multiple times in the event of multiple deselects (e.g. when multiple Standards are selected and the document or filter criteria changes). This property is optional.
onError - An event handler defined by your app to handle error events. In the event of warnings or soft error situations, the widget will do it's best to recover and restore normal working behavior while logging the issue in the console. However, error conditions that are unrecoverable (e.g. authentication errors) will be surfaced to the parent app. The signature of the function must be function (event, message). Message is a human readable message describing the error that occurred. While this parameter is technically optional so the developer can alternatively choose to register this handler directly with jQuery, the developer MUST create a handler using one method or another or there will be no user feedback on error conditions.
Here is an example configuration object for an app that uses the browser for the selection of a single Standard.
Events
The Standards Browser fires or forwards events to the parent app. Registering for most of the events is optional but the app must register for error events because the widget does not handle errors itself. Instead, it forwards them to the parent app so it can display the error using the same approach it displays errors from other elements of the UI.
The following events may be fired during the operation of the widget:
standardSelect - A Standard has been selected. The GUID of the Standard is forwarded with the event. The parent app may choose to ignore such events or it may take some action like enable buttons that allow the user to take action (like add the Standard to a list or close the selection card or dialog).
standardDoubleClick - A Standard has been double clicked. The GUID of the Standard is forwarded with the event. The parent app may choose to ignore such events or it may take some action like add the Standard to a list or close the selection card or dialog. Note that due to the way double clicks are handled in browsers, a double click action will actually create a select event for the Standard being clicked, followed by deselect events for ALL selected Standards followed by a double click event for the Standard being clicked.
standardDeselect - A Standard has been deselected. The GUID of the Standard is forwarded with the event. The parent app may choose to ignore such events or it may take some action like disable buttons. Note that if the user has multiple Standards selected and does something like change the search criteria or publication, the parent app will receive multiple "standardDeselect" events rapidly - one for each selected Standard.
error - An error has occurred and the widget is unable to self recover in a meaningful way.
Methods
The Standards Browser supports the following methods to help the parent app interact with it.
getConfiguration - Returns the uiEntityState object containing the current configuration. This will help the parent app re-launch the widget in the same state as it was when the user closed it. E.g. var state = $('.standardsBrowser').standardsBrowser('getConfiguration');
getSelection - Returns an array of GUIDs listing every Standard that is currently selected in the UI. E.g. var listGuids = $('.standardsBrowser').standardsBrowser('getSelection');
Minimum Standards Browser - This is a minimum app that hosts the Standards Browser. Beyond illustrating the basics of using embeddable widgets in an app, this example shows the basic JSON body of the currently selected Standard. You can see the browser in action here.
Integrated Relationship Browser - This is a version of the Relationship Browser app that uses the Standards Browser rather in place of the home-grown browser from the original Relationship Browser app. You can see it in action here.
Common Integration Scenarios
Simple Single Selector Pop-Up
One common situation is having the user select a single Standard. You may want to do this when prompting a teacher to select a Standard related to a test item or starting the process of searching for items by alignment. The integration may look something like this:
Create a pop-up window (or div) that contains the Standards Browser widget in single select mode and buttons for "OK" and "Close".
Disable the "OK" button by default.
Listen for onStandardSelect events. When you receive one, enable the OK button.
Listen for onStandardDeselect events. When you receive one, disable the OK button.
Listen for onStandardDoubleClick events. When you receive one, record the GUID, close the dialog and return control to the parent app.
If the user selects OK:
Call getSelection to retrieve the selected Standard, record the GUID
Optionally call getConfiguration on the StandardsBrowser to grab the user selections for restoration later
Close the dialog and return control to the parent app
Multiple Selector with a Managed List of Standards
Another common situation is having the user manage a list of Standards. This may come up when you want to allow a teacher to search for materials related to curriculum for the next quarter. The integration may look something like this:
Create an area on the page that contains the Standards Browser widget in multiselect mode as well as a separate list (we'll call this standardsList) and arrow buttons to allow user to add Standards to the standardsList and remove Standards from the list (perhaps ">>" and "<<" or "Add" and "Remove" buttons). You may also want some sort of Action button.
Disable the "Add" button by default.
Listen for onStandardSelect events. When you receive one, enable the "Add" button.
Listen for onStandardDeselect events. When you receive one, check getSelection to see if there are any Standards still selected. If not, disable the "Add" button.
Listen for onStandardDoubleClick events. When you receive one, add the Standard related to the GUID to the list.
Listen for click events on the "Add" button. When you receive one, add the Standard related to the GUID to the list.
Listen for selection events on the standardsList. When you receive one, enable the "Remove" button.
Listen for deselection events on the standardsList. When you receive one, check to see if there are any Standards selected in the standardsList. If not, disable the "Remove" button.
Listen for click events on the "Remove" button. When you receive one, remove the selected Standard from the standardsList.
Listen for click events on the "Action" button. When you receive one:
Gather the list of Standards from standardsList
Optionally call getConfiguration on the StandardsBrowser to grab the user selections for restoration later
GET /rest/v4.1/assets?partner.id=text&auth.signature=text&auth.expires=text HTTP/1.1
Host: api.abconnect.instructure.com
Accept: */*
{
// The ID of the template.
"id": 1,
// The ID of the Course the template belongs to.
"course_id": 2,
// Time when the last export was completed
"last_export_completed_at": "2013-08-28T23:59:00-06:00",
// Number of associated courses for the template
"associated_course_count": 3,
// Details of the latest migration
"latest_migration": null
}
{
// The ID of the migration.
"id": 1,
// The ID of the template the migration belongs to. Only present when querying a
// blueprint course.
"template_id": 2,
// The ID of the associated course's blueprint subscription. Only present when
// querying a course associated with a blueprint.
"subscription_id": 101,
// The ID of the user who queued the migration.
"user_id": 3,
// Current state of the content migration: queued, exporting, imports_queued,
// completed, exports_failed, imports_failed
"workflow_state": "running",
// Time when the migration was queued
"created_at": "2013-08-28T23:59:00-06:00",
// Time when the exports begun
"exports_started_at": "2013-08-28T23:59:00-06:00",
// Time when the exports were completed and imports were queued
"imports_queued_at": "2013-08-28T23:59:00-06:00",
// Time when the imports were completed
"imports_completed_at": "2013-08-28T23:59:00-06:00",
// User-specified comment describing changes made in this operation
"comment": "Fixed spelling in question 3 of midterm exam"
}
// A set of restrictions on editing for copied objects in associated courses
{
// Restriction on main content (e.g. title, description).
"content": true,
// Restriction on points possible for assignments and graded learning objects
"points": true,
// Restriction on due dates for assignments and graded learning objects
"due_dates": false,
// Restriction on availability dates for an object
"availability_dates": true
}
// Describes a learning object change propagated to associated courses from a
// blueprint course
{
// The ID of the learning object that was changed in the blueprint course.
"asset_id": 2,
// The type of the learning object that was changed in the blueprint course.
// One of 'assignment', 'attachment', 'discussion_topic', 'external_tool',
// 'quiz', 'wiki_page', 'syllabus', or 'settings'. For 'syllabus' or
// 'settings', the asset_id is the course id.
"asset_type": "assignment",
// The name of the learning object that was changed in the blueprint course.
"asset_name": "Some Assignment",
// The type of change; one of 'created', 'updated', 'deleted'
"change_type": "created",
// The URL of the changed object
"html_url": "https://canvas.example.com/courses/101/assignments/2",
// Whether the object is locked in the blueprint
"locked": false,
// A list of ExceptionRecords for linked courses that did not receive this
// update.
"exceptions": [{"course_id":101,"conflicting_changes":["points"]}]
}
// Lists associated courses that did not receive a change propagated from a
// blueprint
{
// The ID of the associated course
"course_id": 101,
// A list of change classes in the associated course's copy of the item that
// prevented a blueprint change from being applied. One or more of ['content',
// 'points', 'due_dates', 'availability_dates'].
"conflicting_changes": ["points"]
}
// Associates a course with a blueprint
{
// The ID of the blueprint course subscription
"id": 101,
// The ID of the blueprint template the associated course is subscribed to
"template_id": 1,
// The blueprint course subscribed to
"blueprint_course": {"id":2,"name":"Biology 100 Blueprint","course_code":"BIOL 100 BP","term_name":"Default term"}
}
Whether course settings should be copied over to associated courses. Defaults to true for newly associated courses.
send_item_notifications
boolean
By default, new-item notifications are suppressed in blueprint syncs. If this option is set, teachers and students may receive notifications for items such as announcements and assignments that are created in associated courses (subject to the usual notification settings). This option requires the Blueprint Item Notifications feature to be enabled.
publish_after_initial_sync
boolean
If set, newly associated courses will be automatically published after the sync completes
restricted
boolean
Whether to apply restrictions.
restrictions
BlueprintRestriction
(Optional) If the object is restricted, this specifies a set of restrictions. If not specified, the course-level restrictions will be used. See Course API update documentation
redirect_uri
Required
The URL where the user will be redirected after authorization. The domain of this URL must match the domain of the redirect_uri stored on the developer key, or it must be a subdomain of that domain. For native applications, currently the only supported value is urn:ietf:wg:oauth:2.0:oob, signifying that the credentials will be retrieved out-of-band using an embedded browser or other functionality.
state
Optional
Your application can pass Canvas an arbitrary piece of state in this parameter, which will be passed back to your application in Step 2. It's strongly encouraged that your application pass a unique identifier in the state parameter, and then verify in Step 2 that the state you receive back from Canvas is the same expected value. Failing to do this opens your application to the possibility of logging the wrong person in, as described here.
scope
Optional
This can be used to specify what information the Canvas API access token will provide access to. Canvas API scopes may be found beneath their corresponding endpoints in the "resources" documentation pages. If the developer key does not require scopes and no scope parameter is specified, the access token will have access to all scopes. If the developer key does require scopes and no scope parameter is specified, Canvas will respond with "invalid_scope." To successfully pass multiple scope values, the scope parameter is included once, with multiple values separated by spaces. Passing multiple scope parameters, as is common in other areas of Canvas, causes only the last value to be applied to the generated token.
purpose
Optional
This can be used to help the user identify which instance of an application this token is for. For example, a mobile device application could provide the name of the device.
force_login
Optional
Set to '1' if you want to force the user to enter their credentials, even if they're already logged into Canvas. By default, if a user already has an active Canvas web session, they will not be asked to re-enter their credentials.
unique_id
Optional
Set to the user's username to be populated in the login form in the event that the user must authenticate.
prompt
Optional
If set to none, Canvas will immediately redirect to the redirect_uri. If the caller has a valid session with a "remember me" token or a token from a trusted Developer Key, the redirect will contain a code=XYZ param. If the caller has no session, the redirect will contain an error=login_required param. If the caller has a session, but no "remember me" or trusted token, the redirect will contain an error=interaction_required param.
client_secret
Required for grant_types: authorization_code, refresh_token
The client secret for your registered application.
redirect_uri
Required for grant_types: authorization_code, refresh_token
If a redirect_uri was passed to the initial request in step 1, the same redirect_uri must be given here.
code
Required for grant_type: authorization_code
Required if grant_type is authorization_code. The code you received in a redirect response.
refresh_token
Required for grant_type: refresh_token
Required if grant_type is refresh_token. The refresh_token you received in a redirect response.
client_assertion_type
Required for grant_type: client_credentials
Currently the only supported value for this field is `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`.
client_assertion
Required for grant_type: client_credentials
The signed jwt used to request an access token. Includes the value of Developer Key id as the sub claim of the jwt body. Should be signed by the private key of the stored public key on the DeveloperKey.
scope
Required for grant_type: client_credentials
A list of scopes to be granted to the token. Currently only IMS defined scopes may be used.
The OAuth2 refresh token.
expires_in
Seconds until the access token expires.
canvas_region
For hosted Canvas, the AWS region (e.g. us-east-1) in which the institution that provided this token resides. For local or open source Canvas, this will have a value of "unknown". This field is safe to ignore.
The scope or space delimited list of scopes granted for the access token.
GET /rest/v4.1/asset_collections/{guid}?partner.id=text&auth.signature=text&auth.expires=text HTTP/1.1
Host: api.abconnect.instructure.com
Accept: */*
Appointment Groups
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Appointment Groups API
API for creating, accessing and updating appointment groups. Appointment groups provide a way of creating a bundle of time slots that users can sign up for (e.g. "Office Hours" or "Meet with professor about Final Project"). Both time slots and reservations of time slots are stored as Calendar Events.
Create and return a new appointment group. If new_appointments are specified, the response will return a new_appointments array (same format as appointments array, see “List appointment groups” action)
Request Parameters:
Parameter
Type
Description
appointment_group[context_codes][]
Required string
Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group.
appointment_group[sub_context_codes][]
string
Array of sub context codes (course sections or a single group category) this group should be linked to. Used to limit the appointment group to particular sections. If a group category is specified, students will sign up in groups and the participant_type will be “Group” instead of “User”.
Update and return an appointment group. If new_appointments are specified, the response will return a new_appointments array (same format as appointments array, see “List appointment groups” action).
Request Parameters:
Parameter
Type
Description
appointment_group[context_codes][]
Required string
Array of context codes (courses, e.g. course_1) this group should be linked to (1 or more). Users in the course(s) with appropriate permissions will be able to sign up for this appointment group.
appointment_group[sub_context_codes][]
string
Array of sub context codes (course sections or a single group category) this group should be linked to. Used to limit the appointment group to particular sections. If a group category is specified, students will sign up in groups and the participant_type will be “Group” instead of “User”.
A paginated list of users that are (or may be) participating in this appointment group. Refer to the Users API for the response fields. Returns no results for appointment groups with the “Group” participant_type.
Request Parameters:
Parameter
Type
Description
registration_status
string
Limits results to the a given participation status, defaults to “all”
A paginated list of student groups that are (or may be) participating in this appointment group. Refer to the Groups API for the response fields. Returns no results for appointment groups with the “User” participant_type.
Request Parameters:
Parameter
Type
Description
registration_status
string
Limits results to the a given participation status, defaults to “all”
Return the next appointment available to sign up for. The appointment is returned in a one-element array. If no future appointments are available, an empty array is returned.
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Authentication Providers API
An AuthenticationProvider object looks like:
// Date and time for an appointment
{
// The appointment identifier.
"id": 987,
// Start time for the appointment
"start_at": "2012-07-20T15:00:00-06:00",
// End time for the appointment
"end_at": "2012-07-20T15:00:00-06:00"
}
{
// The ID of the appointment group
"id": 543,
// The title of the appointment group
"title": "Final Presentation",
// The start of the first time slot in the appointment group
"start_at": "2012-07-20T15:00:00-06:00",
// The end of the last time slot in the appointment group
"end_at": "2012-07-20T17:00:00-06:00",
// The text description of the appointment group
"description": "Es muy importante",
// The location name of the appointment group
"location_name": "El Tigre Chino's office",
// The address of the appointment group's location
"location_address": "Room 234",
// The number of participant who have reserved slots (see include[] argument)
"participant_count": 2,
// The start and end times of slots reserved by the current user as well as the
// id of the calendar event for the reservation (see include[] argument)
"reserved_times": [{"id":987,"start_at":"2012-07-20T15:00:00-06:00","end_at":"2012-07-20T15:00:00-06:00"}],
// Boolean indicating whether observer users should be able to sign-up for an
// appointment
"allow_observer_signup": false,
// The context codes (i.e. courses) this appointment group belongs to. Only
// people in these courses will be eligible to sign up.
"context_codes": ["course_123"],
// The sub-context codes (i.e. course sections and group categories) this
// appointment group is restricted to
"sub_context_codes": [course_section_234],
// Current state of the appointment group ('pending', 'active' or 'deleted').
// 'pending' indicates that it has not been published yet and is invisible to
// participants.
"workflow_state": "active",
// Boolean indicating whether the current user needs to sign up for this
// appointment group (i.e. it's reservable and the
// min_appointments_per_participant limit has not been met by this user).
"requiring_action": true,
// Number of time slots in this appointment group
"appointments_count": 2,
// Calendar Events representing the time slots (see include[] argument) Refer to
// the Calendar Events API for more information
"appointments": [],
// Newly created time slots (same format as appointments above). Only returned
// in Create/Update responses where new time slots have been added
"new_appointments": [],
// Maximum number of time slots a user may register for, or null if no limit
"max_appointments_per_participant": 1,
// Minimum number of time slots a user must register for. If not set, users do
// not need to sign up for any time slots
"min_appointments_per_participant": 1,
// Maximum number of participants that may register for each time slot, or null
// if no limit
"participants_per_appointment": 1,
// 'private' means participants cannot see who has signed up for a particular
// time slot, 'protected' means that they can
"participant_visibility": "private",
// Indicates how participants sign up for the appointment group, either as
// individuals ('User') or in student groups ('Group'). Related to
// sub_context_codes (i.e. 'Group' signups always have a single group category)
"participant_type": "User",
// URL for this appointment group (to update, delete, etc.)
"url": "https://example.com/api/v1/appointment_groups/543",
// URL for a user to view this appointment group
"html_url": "http://example.com/appointment_groups/1",
// When the appointment group was created
"created_at": "2012-07-13T10:55:20-06:00",
// When the appointment group was last updated
"updated_at": "2012-07-13T10:55:20-06:00"
}
Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. Defaults to false.
appointment_group[participants_per_appointment]
integer
Maximum number of participants that may register for each time slot. Defaults to null (no limit).
Maximum number of time slots a user may register for.
appointment_group[new_appointments][X][]
string
Nested array of start time/end time pairs indicating time slots for this appointment group. Refer to the example request.
appointment_group[participant_visibility]
string
“private”
participants cannot see who has signed up for a particular time slot
“protected”
participants can see who has signed up. Defaults to “private”.
Allowed values: private, protected
appointment_group[allow_observer_signup]
boolean
Whether observer users can sign-up for an appointment. Defaults to false.
appointment_group[title]
string
Short title for the appointment group.
appointment_group[description]
string
Longer text description of the appointment group.
appointment_group[location_name]
string
Location name of the appointment group.
appointment_group[location_address]
string
Location address.
appointment_group[publish]
boolean
Indicates whether this appointment group should be published (i.e. made available for signup). Once published, an appointment group cannot be unpublished. Defaults to false.
appointment_group[participants_per_appointment]
integer
Maximum number of participants that may register for each time slot. Defaults to null (no limit).
Add external authentication provider(s) for the account. Services may be Apple, CAS, Facebook, GitHub, Google, LDAP, LinkedIn, Microsoft, OpenID Connect, or SAML.
Each authentication provider is specified as a set of parameters as described below. A provider specification must include an ‘auth_type’ parameter with a value of ‘apple’, ‘canvas’, ‘cas’, ‘clever’, ‘facebook’, ‘github’, ‘google’, ‘ldap’, ‘linkedin’, ‘microsoft’, ‘openid_connect’, or ‘saml’. The other recognized parameters depend on this auth_type; unrecognized parameters are discarded. Provider specifications not specifying a valid auth_type are ignored.
You can set the ‘position’ for any provider. The config in the 1st position is considered the default. You can set ‘jit_provisioning’ for any provider besides Canvas. You can set ‘mfa_required’ for any provider.
For Apple, the additional recognized parameters are:
client_id [Required]
The developer’s client identifier, as provided by WWDR. Not available if configured globally for Canvas.
login_attribute [Optional]
The attribute to use to look up the user’s login in Canvas. Either ‘sub’ (the default), or ‘email’
federated_attributes [Optional]
See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘firstName’, ‘lastName’, and ‘sub’.
For Canvas, the additional recognized parameter is:
self_registration
‘all’, ‘none’, or ‘observer’ - who is allowed to register as a new user
For CAS, the additional recognized parameters are:
auth_base
The CAS server’s URL.
log_in_url [Optional]
An alternate SSO URL for logging into CAS. You probably should not set this.
For Clever, the additional recognized parameters are:
client_id [Required]
The Clever application’s Client ID. Not available if configured globally for Canvas.
client_secret [Required]
The Clever application’s Client Secret. Not available if configured globally for Canvas.
district_id [Optional]
A district’s Clever ID. Leave this blank to let Clever handle the details with its District Picker. This is required for Clever Instant Login to work in a multi-tenant environment.
login_attribute [Optional]
The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), ‘sis_id’, ‘email’, ‘student_number’, or ‘teacher_number’. Note that some fields may not be populated for all users at Clever.
federated_attributes [Optional]
See FederatedAttributesConfig. Valid provider attributes are ‘id’, ‘sis_id’, ‘email’, ‘student_number’, and ‘teacher_number’.
For Facebook, the additional recognized parameters are:
app_id [Required]
The Facebook App ID. Not available if configured globally for Canvas.
app_secret [Required]
The Facebook App Secret. Not available if configured globally for Canvas.
login_attribute [Optional]
The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), or ‘email’
federated_attributes [Optional]
See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘first_name’, ‘id’, ‘last_name’, ‘locale’, and ‘name’.
For GitHub, the additional recognized parameters are:
domain [Optional]
The domain of a GitHub Enterprise installation. I.e. github.mycompany.com. If not set, it will default to the public github.com.
client_id [Required]
The GitHub application’s Client ID. Not available if configured globally for Canvas.
client_secret [Required]
The GitHub application’s Client Secret. Not available if configured globally for Canvas.
login_attribute [Optional]
The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), or ‘login’
federated_attributes [Optional]
See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘id’, ‘login’, and ‘name’.
For Google, the additional recognized parameters are:
client_id [Required]
The Google application’s Client ID. Not available if configured globally for Canvas.
client_secret [Required]
The Google application’s Client Secret. Not available if configured globally for Canvas.
hosted_domain [Optional]
A Google Apps domain to restrict logins to. See
login_attribute [Optional]
The attribute to use to look up the user’s login in Canvas. Either ‘sub’ (the default), or ‘email’
federated_attributes [Optional]
See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘family_name’, ‘given_name’, ‘locale’, ‘name’, and ‘sub’.
For LDAP, the additional recognized parameters are:
auth_host
The LDAP server’s URL.
auth_port [Optional, Integer]
The LDAP server’s TCP port. (default: 389)
auth_over_tls [Optional]
Whether to use TLS. Can be ‘simple_tls’, or ‘start_tls’. For backwards compatibility, booleans are also accepted, with true meaning simple_tls. If not provided, it will default to start_tls.
auth_base [Optional]
A default treebase parameter for searches performed against the LDAP server.
auth_filter
LDAP search filter. Use {{login}} as a placeholder for the username supplied by the user. For example: “(sAMAccountName={{login}})”.
identifier_format [Optional]
The LDAP attribute to use to look up the Canvas login. Omit to use the username supplied by the user.
auth_username
Username
auth_password
Password
For LinkedIn, the additional recognized parameters are:
client_id [Required]
The LinkedIn application’s Client ID. Not available if configured globally for Canvas.
client_secret [Required]
The LinkedIn application’s Client Secret. Not available if configured globally for Canvas.
login_attribute [Optional]
The attribute to use to look up the user’s login in Canvas. Either ‘id’ (the default), or ‘emailAddress’
federated_attributes [Optional]
See FederatedAttributesConfig. Valid provider attributes are ‘emailAddress’, ‘firstName’, ‘id’, ‘formattedName’, and ‘lastName’.
For Microsoft, the additional recognized parameters are:
application_id [Required]
The application’s ID.
application_secret [Required]
The application’s Client Secret (Password)
tenant [Optional]
See / Valid values are ‘common’, ‘organizations’, ‘consumers’, or an Azure Active Directory Tenant (as either a UUID or domain, such as contoso.onmicrosoft.com). Defaults to ‘common’
login_attribute [Optional]
See Valid values are ‘sub’, ‘email’, ‘oid’, or ‘preferred_username’. Note that email may not always be populated in the user’s profile at Microsoft. Oid will not be populated for personal Microsoft accounts. Defaults to ‘sub’
federated_attributes [Optional]
See FederatedAttributesConfig. Valid provider attributes are ‘email’, ‘name’, ‘preferred_username’, ‘oid’, and ‘sub’.
For OpenID Connect, the additional recognized parameters are:
client_id [Required]
The application’s Client ID.
client_secret [Required]
The application’s Client Secret.
authorize_url [Required]
The URL for getting starting the OAuth 2.0 web flow
token_url [Required]
The URL for exchanging the OAuth 2.0 authorization code for an Access Token and ID Token
scope [Optional]
Space separated additional scopes to request for the token. Note that you need not specify the ‘openid’ scope, or any scopes that can be automatically inferred by the rules defined at
end_session_endpoint [Optional]
URL to send the end user to after logging out of Canvas. See
userinfo_endpoint [Optional]
URL to request additional claims from. If the initial ID Token received from the provider cannot be used to satisfy the login_attribute and all federated_attributes, this endpoint will be queried for additional information.
login_attribute [Optional]
The attribute of the ID Token to look up the user’s login in Canvas. Defaults to ‘sub’.
federated_attributes [Optional]
See FederatedAttributesConfig. Any value is allowed for the provider attribute names, but standard claims are listed at
For SAML, the additional recognized parameters are:
metadata [Optional]
An XML document to parse as SAML metadata, and automatically populate idp_entity_id, log_in_url, log_out_url, certificate_fingerprint, and identifier_format
metadata_uri [Optional]
A URI to download the SAML metadata from, and automatically populate idp_entity_id, log_in_url, log_out_url, certificate_fingerprint, and identifier_format. This URI will also be saved, and the metadata periodically refreshed, automatically. If the metadata contains multiple entities, also supply idp_entity_id to distinguish which one you want (otherwise the only entity in the metadata will be inferred). If you provide the URI ‘urn:mace:incommon’ or ‘ukfederation.org.uk’, the InCommon or UK Access Management Federation metadata aggregate, respectively, will be used instead, and additional validation checks will happen (including validating that the metadata has been properly signed with the appropriate key).
idp_entity_id
The SAML IdP’s entity ID
log_in_url
The SAML service’s SSO target URL
log_out_url [Optional]
The SAML service’s SLO target URL
certificate_fingerprint
The SAML service’s certificate fingerprint.
identifier_format
The SAML service’s identifier format. Must be one of:
Update an authentication provider using the same options as the Add authentication provider endpoint. You cannot update an existing provider to a new authentication type.
Restore an authentication provider back to active that was previously deleted. Only available to admins who can manage_account_settings for given root account.
For various cases of mixed SSO configurations, you may need to set some configuration at the account level to handle the particulars of your setup.
This endpoint accepts a PUT request to set several possible account settings. All setting are optional on each request, any that are not provided at all are simply retained as is. Any that provide the key but a null-ish value (blank string, null, undefined) will be UN-set.
You can list the current state of each setting with “show_sso_settings”
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.
The "guid" identifies the standard collection in machine readable format.
The "filters" object
The "filters" object stores the filtering expression for the standard collection. This stores standard hierarchy and global filters which helps to filter to only the desired standards.
Here is a formal description about the filters object. For a practical explanation see the example below.
filters (object, required) - JSON API object for filters object containing various fields like: "filters (standard hierarchy)", "globalFilters"
filters (object) - Standard hierarchy
Example to build a "filter expression" from the "filters" object
Here is a filters object. Let's see how filter expression can be generated from it step-by-step:
The left side of the expression starts with filter[asset] =. There are two elements in the filters.facets array, so there will be two expressions on the right side. For example expressions expr_1 and expr_2. These are the basis of the filtering. The expr_1 is built up from filters.facets[0] and the expr_2 is built up from filters.facets[1].
Expressions are built up from a "field" and set of "values". The filter will give back those assets which have given the "values" on the given "field".
Let's find the "field" values. In the JSON object the "field" is defined by field.id.
Substitute these as "fields" into the filter expression.
Let's find the "values". The variables' names that are holding the "values" are defined by the facet.id. The "values" are those items in the selectedFilters object which have the object-path defined in the facet.id.
The variable for "values_1" is facet.id = "data.guid". Let's gather the values from selectedFilters.data.guid and generate the "values_1".
The variable for "values_2" is facet.id = "data.guid". Let's gather the values from selectedFilters.data.guid and generate the "values_2".
Finally substitute the "values" into the filter expression:
This example will filter only those assets which are in the grade: "Kindergarten" or "9th Grade" and are in the subject: "Mathematics".
To get the available facets for standards check the facet_summary at for details.
Standard Collection
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 name and a guid as reference.
List All Standard Collections
To list Standard Collections the partner has access to, send a GET to the endpoint.
To find a Standard Collection by exact name, send a GET to the endpoint with the collection_name parameter. This gives back only the case sensitive exact match if there is any.
To search Standard Collections by name, send a GET to the endpoint with the search_collection_name
Create a new Standard Collection
To create a Standard Collection within the AB Connects system, you send a POST request to the endpoint. The body of the POST contains the Standard Collection definition in JSON format.
The response will be the same as a GET by GUID request for the created Standard Collection.
Working with Standards Collection
Retrieving the Details of a Standard Collection
To get the Standard Collections you've created, call the endpoint with a GET while supplying the AB GUID for the Standard Collection. To retrieve the GUID, use the list and search functionality.
Modifying a Standard Collection
To update a Standard Collection, send a PATCH to the Standard Collection 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 can update the name or filters fields for the Standard Collection. You can update only one of these or all.
The response will contain the modified Standard Collection just as it would be in a GET by GUID request for the created Standard Collection.
Deleting a Standard Collection
To delete a Standard Collection you've created, send a DELETE the endpoint while supplying the AB GUID for the Standard Collection. If you have the name for the Standard Collection but not the AB GUID, see the section on searching for Standard Collections.
{
// Valid for SAML providers.
"identifier_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
// Valid for all providers.
"auth_type": "saml",
// Valid for all providers.
"id": 1649,
// Valid for SAML providers.
"log_out_url": "http://example.com/saml1/slo",
// Valid for SAML and CAS providers.
"log_in_url": "http://example.com/saml1/sli",
// Valid for SAML providers.
"certificate_fingerprint": "111222",
// Valid for SAML providers.
"requested_authn_context": null,
// Valid for LDAP providers.
"auth_host": "127.0.0.1",
// Valid for LDAP providers.
"auth_filter": "filter1",
// Valid for LDAP providers.
"auth_over_tls": null,
// Valid for LDAP and CAS providers.
"auth_base": null,
// Valid for LDAP providers.
"auth_username": "username1",
// Valid for LDAP providers.
"auth_port": null,
// Valid for all providers.
"position": 1,
// Valid for SAML providers.
"idp_entity_id": "http://example.com/saml1",
// Valid for SAML providers.
"login_attribute": "nameid",
// Valid for SAML providers.
"sig_alg": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
// Just In Time provisioning. Valid for all providers except Canvas (which has
// the similar in concept self_registration setting).
"jit_provisioning": null,
"federated_attributes": null,
// If multi-factor authentication is required when logging in with this
// authentication provider. The account must not have MFA disabled.
"mfa_required": null
}
// Settings that are applicable across an account's authentication
// configuration, even if there are multiple individual providers
{
// The label used for unique login identifiers.
"login_handle_name": "Username",
// The url to redirect users to for password resets. Leave blank for default
// Canvas behavior
"change_password_url": "https://example.com/reset_password",
// If a discovery url is set, canvas will forward all users to that URL when
// they need to be authenticated. That page will need to then help the user
// figure out where they need to go to log in. If no discovery url is
// configured, the first configuration will be used to attempt to authenticate
// the user.
"auth_discovery_url": "https://example.com/which_account",
// If an unknown user url is set, Canvas will forward to that url when a service
// authenticates a user, but that user does not exist in Canvas. The default
// behavior is to present an error.
"unknown_user_url": "https://example.com/register_for_canvas"
}
// A mapping of Canvas attribute names to attribute names that a provider may
// send, in order to update the value of these attributes when a user logs in.
// The values can be a FederatedAttributeConfig, or a raw string corresponding
// to the "attribute" property of a FederatedAttributeConfig. In responses, full
// FederatedAttributeConfig objects are returned if JIT provisioning is enabled,
// otherwise just the attribute names are returned.
{
// A comma separated list of role names to grant to the user. Note that these
// only apply at the root account level, and not sub-accounts. If the attribute
// is not marked for provisioning only, the user will also be removed from any
// other roles they currently hold that are not still specified by the IdP.
"admin_roles": null,
// The full display name of the user
"display_name": null,
// The user's e-mail address
"email": null,
// The first, or given, name of the user
"given_name": null,
// The secondary unique identifier for SIS purposes
"integration_id": null,
// The user's preferred locale/language
"locale": null,
// The full name of the user
"name": null,
// The unique SIS identifier
"sis_user_id": null,
// The full name of the user for sorting purposes
"sortable_name": null,
// The surname, or last name, of the user
"surname": null,
// The user's preferred time zone
"timezone": null
}
// A single attribute name to be federated when a user logs in
{
// The name of the attribute as it will be sent from the authentication provider
"attribute": "mail",
// If the attribute should be applied only when provisioning a new user, rather
// than all logins
"provisioning_only": false,
// (only for email) If the email address is trusted and should be automatically
// confirmed
"autoconfirm": false
}
key (string) - Standard hierarchy element ID (guid or "root")
value (object) - Standard hierarchy element parameters
collections (array) - Array of GUIDs for the elements which are one level below in the hierarchy.
id (GUID) - GUID of the element in the hierarchy. (Same as the key.)
parentId (GUID) - GUID for the element which is one level above in the hierarchy.
state (string) - State is saying if the item element in the hierarchy is selected or not. Values can be: "checked" [+], "indeterminate" [-], "unchecked" [ ]
type (string) - Type of position in the hierarchy. Values in hierarchical order: "region" > "publication" > "document" > "section" > "standard".
globalFilters (object) - Standard global filters: filtering by standard facets
key (string) - Standard facet description. (Eg: "document.publication.regions":)
value (object) - Standard facet parameters
guid (GUID) - GUID of the element in the hierarchy. (Eg.: "A832862C-901A-11DF-A622-0C319DFF4B22")
name (text) - Value of the facet parameter. (Eg.: "California")
parameter. This search uses case insensitive partial matching.
get
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standard_collections]stringOptional
comma separated list of field names
filter[standard_collections]stringOptional
an ODATA-like query string used to filter
sort[standard_collections]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
post
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
namestringRequired
filtersobjectRequired
advanced_searchobjectOptional
Responses
201
Created
application/json
get
Path parameters
guidstringRequired
guid of specified standard collection
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standard_collections]stringOptional
comma separated list of field names
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
guidstringOptional
namestringOptional
Other propertiesanyOptional
Other propertiesanyOptional
400
Bad Request
application/json
401
Authentication Error
application/json
409
Conflict
application/json
422
Unprocessable content
application/json
patch
Path parameters
guidstringRequired
guid of specified standard collection
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
delete
Path parameters
guidstringRequired
guid of specified standard collection
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
filter[asset] = education_levels.grades in ("F1F9FA12-3B53-11E0-A421-F4B24952E9DF", "ABBAABBA-ACDC-ACDC-B042-495E9DFF4B22") and disciplines.subjects.ids in ("495E9DFF-3B53-11E0-B042-C4B222F1FB2F")
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
guidstringOptional
namestringOptional
Other propertiesanyOptional
Other propertiesanyOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/standard_collections
post
/standard_collections
201
Created
get
/standard_collections/{guid}
anyOptional
or
anyOptional
or
anyOptional
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
Create a content migration. If the migration requires a file to be uploaded the actual processing of the file will start once the file upload process is completed. File uploading works as described in the File Upload Documentation except that the values are set on a pre_attachment sub-hash.
For migrations that don’t require a file to be uploaded, like course copy, the processing will begin as soon as the migration is created.
You can use the Progress API to track the progress of the migration. The migration’s progress is linked to with the progress_url value.
The two general workflows are:
If no file upload is needed:
POST to create
Use the Progress specified in progress_url to monitor progress
Use the specified in progress_url to monitor progress
Request Parameters:
Parameter
Type
Description
migration_type
Required string
The type of the migration. Use the endpoint to see all available migrators. Default allowed values: canvas_cartridge_importer, common_cartridge_importer, course_copy_importer, zip_file_importer, qti_converter, moodle_converter
pre_attachment[name]
string
Required if uploading a file. This is the first step in uploading a file to the content migration. See the for details on the file upload workflow.
Update a content migration. Takes same arguments as create except that you can’t change the migration type. However, changing most settings after the migration process has started will not do anything. Generally updating the content migration will be used when there is a file upload problem, or when importing content selectively. If the first upload has a problem you can supply new pre_attachment values to start the process again.
Enumerates the content available for selective import in a tree structure. Each node provides a property copy argument that can be supplied to the Update endpoint to selectively copy the content associated with that tree node and its children. Each node may also provide a sub_items_url or an array of sub_items which you can use to obtain copy parameters for a subset of the resources in a given node.
If no type is sent you will get a list of the top-level sections in the content. It will look something like this:
When a type is provided, nodes may be further divided via sub_items. For example, using type=assignments results in a node for each assignment group and a sub_item for each assignment, like this:
To import the items corresponding to a particular tree node, use the property as a parameter to the Update endpoint and assign a value of 1, for example:
You can include multiple copy parameters to selectively import multiple items or groups of items.
Given a complete course copy or blueprint import content migration, return a mapping of asset ids from the source course to the destination course that were copied in this migration or an earlier one with the same course pair and migration_type (course copy or blueprint).
The returned object’s keys are asset types as they appear in API URLs (announcements, assignments, discussion_topics, files, module_items, modules, pages, and quizzes). The values are a mapping from id in source course to id in destination course for objects of this type.
Example Request:
Example Response:
This documentation is generated directly from the Canvas LMS source code, available on Github.
{
// the unique identifier for the issue
"id": 370663,
// API url to the content migration
"content_migration_url": "https://example.com/api/v1/courses/1/content_migrations/1",
// Description of the issue for the end-user
"description": "Questions in this quiz couldn't be converted",
// Current state of the issue: active, resolved
"workflow_state": "active",
// HTML Url to the Canvas page to investigate the issue
"fix_issue_html_url": "https://example.com/courses/1/quizzes/2",
// Severity of the issue: todo, warning, error
"issue_type": "warning",
// Link to a Canvas error report if present (If the requesting user has
// permissions)
"error_report_html_url": "https://example.com/error_reports/3",
// Site administrator error message (If the requesting user has permissions)
"error_message": "admin only message",
// timestamp
"created_at": "2012-06-01T00:00:00-06:00",
// timestamp
"updated_at": "2012-06-01T00:00:00-06:00"
}
{
// the unique identifier for the migration
"id": 370663,
// the type of content migration
"migration_type": "common_cartridge_importer",
// the name of the content migration type
"migration_type_title": "Canvas Cartridge Importer",
// API url to the content migration's issues
"migration_issues_url": "https://example.com/api/v1/courses/1/content_migrations/1/migration_issues",
// attachment api object for the uploaded file may not be present for all
// migrations
"attachment": "{"url"=>"https://example.com/api/v1/courses/1/content_migrations/1/download_archive"}",
// The api endpoint for polling the current progress
"progress_url": "https://example.com/api/v1/progress/4",
// The user who started the migration
"user_id": 4,
// Current state of the content migration: pre_processing, pre_processed,
// running, waiting_for_select, completed, failed
"workflow_state": "running",
// timestamp
"started_at": "2012-06-01T00:00:00-06:00",
// timestamp
"finished_at": "2012-06-01T00:00:00-06:00",
// file uploading data, see {file:file.file_uploads.html File Upload
// Documentation} for file upload workflow This works a little differently in
// that all the file data is in the pre_attachment hash if there is no
// upload_url then there was an attachment pre-processing error, the error
// message will be in the message key This data will only be here after a create
// or update call
"pre_attachment": "{"upload_url"=>"", "message"=>"file exceeded quota", "upload_params"=>{}}"
}
{
// The value to pass to the create endpoint
"type": "common_cartridge_importer",
// Whether this endpoint requires a file upload
"requires_file_upload": true,
// Description of the package type expected
"name": "Common Cartridge 1.0/1.1/1.2 Package",
// A list of fields this system requires
"required_settings": ["source_course_id"]
}
The (1-based) position to insert the imported items into the course (if insert_into_module_id is supplied). If this parameter is omitted, items will be added to the end of the module.
settings[move_to_assignment_group_id]
integer
The id of an assignment group in the target course. If provided, all imported assignments will be moved to the given assignment group.
settings[importer_skips]
Array
Set of importers to skip, even if otherwise selected by migration settings.
Import the “use as blueprint course” setting as well as the list of locked items from the source course or package. The destination course must not be associated with an existing blueprint course and cannot have any student or observer enrollments.
date_shift_options[shift_dates]
boolean
Whether to shift dates in the copied course
date_shift_options[old_start_date]
Date
The original start date of the source content/course
date_shift_options[old_end_date]
Date
The original end date of the source content/course
date_shift_options[new_start_date]
Date
The new start date for the content/course
date_shift_options[new_end_date]
Date
The new end date for the source content/course
date_shift_options[day_substitutions][X]
integer
Move anything scheduled for day ‘X’ to the specified day. (0-Sunday, 1-Monday, 2-Tuesday, 3-Wednesday, 4-Thursday, 5-Friday, 6-Saturday)
date_shift_options[remove_dates]
boolean
Whether to remove dates in the copied course. Cannot be used in conjunction with shift_dates.
selective_import
boolean
If set, perform a selective import instead of importing all content. The migration will identify the contents of the package and then stop in the waiting_for_select workflow state. At this point, use the List items endpoint to enumerate the contents of the package, identifying the copy parameters for the desired content. Then call the Update endpoint and provide these copy parameters to start the import.
select
Hash
For course_copy_importer migrations, this parameter allows you to select the objects to copy without using the selective_import argument and waiting_for_select state as is required for uploaded imports (though that workflow is also supported for course copy migrations). The keys are object types like ‘files’, ‘folders’, ‘pages’, etc. The value for each key is a list of object ids. An id can be an integer or a string. Multiple object types can be selected in the same call.
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Enrollments API
API for creating and viewing course enrollments
Managing and Predicting Relationships
One of the most powerful features of AB Connect is the ability to build, predict and navigate relationships. These relationships are managed by direct connection (e.g. relating a Standard to an Asset), indirect reference (e.g. relating entities based on mutual relationships with other entities), prediction (when the system suggests a relationship) and through other system derived means. The following sections explain how to manage these relationships.
Note that some relationships are complex having multiple properties that exist on the relationship. These relationships are represented in AB Connect as relational objects and have their own endpoints. These relationship objects are not covered here but have their own sections in the documentation.
Content Enrichment Overview
AB Connect offers a Content Enrichment service which helps to establish, maintain and predict relationships between Assets (content, assessment items, etc.), Standards, Topics, Concepts and other Assets. This system uses the Asset metadata profile, learning algorithms and relationship data we've built over 15 years of aligning content. Content Enrichment makes your Assets more discoverable and aids in building relationships. Content Enrichment uses intermediaries like Topics, Concepts and Key Ideas when relating Asset and Standards.
Depending on the URL given, return a paginated list of either (1) all of the enrollments in a course, (2) all of the enrollments in a section or (3) all of a user’s enrollments. This includes student, teacher, TA, and observer enrollments.
If a user has multiple enrollments in a context (e.g. as a teacher and a student or in multiple course sections), each enrollment will be listed separately.
note: Currently, only a root level admin user can return other users’ enrollments. A user can, however, return his/her own enrollments.
Enrollments scoped to a course context will include inactive states by default if the caller has account admin authorization and the state[] parameter is omitted.
Request Parameters:
Parameter
Type
Description
type[]
string
A list of enrollment types to return. Accepted values are ‘StudentEnrollment’, ‘TeacherEnrollment’, ‘TaEnrollment’, ‘DesignerEnrollment’, and ‘ObserverEnrollment.’ If omitted, all enrollment types are returned. This argument is ignored if role is given.
role[]
string
A list of enrollment roles to return. Accepted values include course-level roles created by the as well as the base enrollment types accepted by the type argument above.
Conclude, deactivate, or delete an enrollment. If the task argument isn’t given, the enrollment will be concluded.
Request Parameters:
Parameter
Type
Description
task
string
The action to take on the enrollment. When inactive, a user will still appear in the course roster to admins, but be unable to participate. (“inactivate” and “deactivate” are equivalent tasks)
The AB Topic Taxonomy is a broad taxonomy used for general categorization of Standards. Every Standard in the core four subjects (language arts, math, science and social studies) is associated with at least one Topic. The use of Topics builds relationships quickly and easily. When a Standard is related to an Asset, a predicted relationship between the Asset and one or more Topics is established. This is a bi-directional capability so establishing a relationship between a Topic and an Asset will create predicted relationships between the Asset and Standards (typically multiple Standards - across all authorities in your license). The use of Topics to enrich your Assets is a very efficient way to power search-by-Standard capabilities in your system and enable the fast discovery of relationships.
The AB Concept Taxonomy is a granular means for identifying precise relationships between Standards and Assets. Concepts represent individual notions covered by an Asset or Standard. Concepts are linked together to build Key Ideas that are then associated with Standards. Key Ideas are similar to unpacked Standards and are a key component to the AB Content Enrichment Engine. As an Asset's Concept profile is defined, the prediction engine is able to more accurately predict relationships between the Asset and new Standards. Note that the prediction engine utilizes the Disciplines and Education Levels specified in the Assets and Standards profiles (when present) to assist in predictions. Connecting an Asset to Concepts or Standards outside of the Asset's Discipline and Education Level profile will not aid or alter the predictions or clarifications. See Managing Relationships Between Assets and Concepts
for details on tagging content with Concepts and the section on Standards for information on retrieving Key Idea data from a Standard.
However you choose to enrich your content, calling the Predictions endpoint engages the engine to predict relationships between your Asset and other entities in the system. While many aspects of the Asset metadata profile can impact predictions, the predictions are not actually generated until the predictions endpoint is called. This is true for changes in disciplines, education levels and relationships to Standards, Topics, Concepts and donors. See Managing and Predicting Relationships for details on using the prediction engine.
While a detailed explanation of Content Enrichment is beyond the scope of this API documentation, you can get more information by contacting AB Support at Instructure or your sales representative.
Note that use of Academic Benchmarks Assets, Topics, Concepts and Clarifier is enabled through licensing. See the section on Licensing Considerations for a discussion on how to enable these features.
The Effect of Metadata on Predictions and Clarifications
AB Connect uses the metadata profiles of Topics, Standards and Assets to understand relationships, recommend additional relationships and determine where the recommendation engine needs further clarification. The profiles can impact the engine in many ways. A couple of things to be aware of when working with AB Connect and relationships between Assets, Topics and Standards:
If disciplines and education levels are defined on an Asset, they should match or at least overlap with those on the Topic or Standard if you hope to have the relationship shape the recommendations made by the system. When the descriptions do not match, the engine ignores the relationship for the purpose of recommendations and requesting clarifications.
Standards that do not have an utilization type of "alignable" typically do not impact future recommendations for the Asset relationships.
If you are working with Assets that are using v2 of the prediction engine (see the prediction_algorithm field), creating, deleting and modifying relationships between the Asset and Standards, Concepts or Topics upgrades the prediction algorithm to v3.
For example, if you have a 3rd grade Asset (education_levels.grades.code eq '3') and create a relationship between that Asset and the middle school Topic "Solving Equations", the system will not predict any relationships to Standards because the grade ranges don't match between the Topic and Asset.
Locating Recent Changes to Relationships Between Assets and Standards
Some AB Connect customers prefer to cache Asset and Standards data within their system and refresh the data periodically. To make this process more efficient and to support customer processes where changes may go through an internal review process, AB Connect allows you to search for Assets by the date that a relationship between a Standard and Asset changed. To do this, search for Assets where date_alignments_modified_utc is greater than a certain point in time. E.g.
Once you have a list of Assets where their relationships with Standards have changed recently, you can filter on the related Standards by date to see which specific changes have been made. E.g.
Retrieving Standards Related to an Asset that Meet Certain Criteria
Some AB Connect customers display "alignments" (relationships between Assets and Standards) with their content. Often, they will know the Authority associated with the browser (e.g. a teacher registered in an LMS may have their state in their profile). In this case, it is possible to retrieve only the given Authority's Standards related to this Asset. To do this, search for Standards related to the Asset and filter the Standards by Authority. E.g.
Retrieving Topics Related to an Asset that Meet Certain Criteria
Similar to the Standards based example above, you may want to retrieve related Topics that are accepted. To do this, search for Topics related to the Asset and filter the disposition. E.g.
Retrieving Concepts Related to an Asset that Meet Certain Criteria
Similar to the examples above, you may want to retrieve related Concepts that are central. To do this, search for Concepts related to the Asset and filter the emphasis. E.g.
Managing Relationships Between Assets and Standards
AB Connect allows you to connect your Assets directly to Standards. Establishing relationships between Assets and Standards can power services like searching for Assets by Standards and gap analysis. Building (and rejecting) direct relationships like this can also be the first step accelerating Content Enrichment. Direct relationships can be very helpful in building and managing your Asset library but full Content Enrichment with intermediaries like Topics and Concepts can greatly accelerate the process and broaden the network of relationships quickly and efficiently.
Creating Relationships
You can create (and add) a direct relationship between an Asset and Standards by POSTing to /assets/{guid}/alignments. You can "accept" or "reject" a direct relationship. Accepting one is indicating that the relationship has been reviewed and is correct. Rejecting a relationship indicates that the relationship has been reviewed and there is no relationship between the Asset and Standard. This is known as the disposition of the relationship.
In addition to specifying the disposition, for accepted relationships, you can associate tags with the relationship. The meaning of the tag is partner defined and the following values are accepted:
Excellent
Good
Moderate
Encompassing
Exact
Related
Partial
Limited
Best One
Maybe
Since JSON API does not allow direct properties on relationships, the disposition and tags are stored in the relationship metadata.
Updating and Deleting All Relationships
To replace all existing relationships between and Asset and some Standards, PATCH the endpoint sending the new relationships in the PATCH body. The body is in the same format as when creating a relationship. In JSON API, relationships either exist or do not, so there isn't a mechanism to directly support altering relationship properties of a subset of the relationships. In order to alter the metadata on one or more relationships (e.g. disposition or tags), you must PATCH all relationships including the desired metadata for each relationship. Any relationships or relationship metadata properties NOT included in the PATCH body will be removed. Note that you can remove ALL relationships between Assets and Standards by sending an empty set in the PATCH body. E.g. { "data": [] }
Removing Specific Relationships
It is possible to remove specific relationships between an Asset and one or more Standards using the DELETE method and including the Standards you'd like to remove from the Asset.
Filtering and Paging Relationships Between Assets and Standards
AB Connect allows you to filter and page through the list of Standards related to an Asset. This can be helpful if you are wanting to limit the alignments you are showing a user to those in their specified state or if you are caching Assets and only want to retrieve alignments that have changed since the last time you cached the data (for example).
You can filter and sort on relationship properties like meta.disposition and meta.date_modified_utc or on Standards properties. If you are using Standards properties in your filtering and sorting, you are limited to the fields listed in the Standards section of the Filtering Resources by Properties on Related Resources documentation. Note that when using Standards properties for filtering here, you can drop the alignments. from the property name.
Fetching Related Standards
Filtering and Paging Deleted Alignments
AB Connect allows you to filter and page through the list of Standards that used to be related to an Asset. This can be helpful if you are caching Assets and only want to retrieve alignments that have changed since the last time you cached the data. This is the only way to get the list of deleted alignments.
Fetching Formerly Related Standards
Managing Relationships Between Assets and Topics
If you have licensed the Academic Benchmarks Topic Taxonomy (here referred to simply as Topics), Topics can assist with Asset searches and be a powerful tool to help establish relationships between Assets and Standards. One of the most powerful features of AB Connect is the ability to build, predict and navigate relationships. These relationships are managed by direct connection (e.g. relating a Topic to an Asset), indirect reference (e.g. automatically relating to Topics based in their relationships to Standards) and through other system derived means. The process of developing these relationships and describing an Asset with metadata is known as Content Enrichment because by associating an asset with the Academic Benchmark metadata, you gain access to a rich network of additional relationships that can serve to power search and discovery, alignment processes, and navigability within content.
Content Enrichment with the Academic Benchmarks Topic Taxonomy enables coarse-grained description and relationship management. The Topic Taxonomy was developed with browsability in mind, ...not only controlling the vocabulary, but also the organization in a rigid 4-level hierarchy that includes Subject > Grade Band > Branch > Topic. Topics represetn what should be learned at a broad level. The coarse-grained nature of the AB Topic Taxonomy enables a simple relationship management mechanism and can be used in your search technologies for advanced and efficient discovery capabilities. At its simplest, establishing a relationship between an Asset and a Topic enables AB Connect to predict relationships between the Asset and Standards. This is a bi-directional relationship, so the process could alternatively start with creating a direct relationship between a Standard and Asset which would predict relationships between the Asset and one or more Topics.
Create a relationship between the Topic and Asset (see below)
Update the predictions made by the system (see ).
Now if you , you'll see the accepted Topic relationship and a number of predicted Standards relationships
You can review the Standards and confirm the relationship between the strong matches and the Asset by
You can also reject bad matches and delete erroneous matches.
Note that use of Academic Benchmarks Assets, Topics, Concepts and Clarifier is enabled through licensing. See the section on Licensing Considerations for a discussion on how to enable these features.
Creating Relationships
You can create (and add) a direct relationship between an Asset and Topics by POSTing to /assets/{guid}/topics. You can "accept" or "reject" a direct relationship. Accepting one is indicating that the relationship has been reviewed and is correct. Rejecting a relationship indicates that the relationship has been reviewed and there is no relationship between the Asset and Topic. This is known as the disposition of the relationship. Since JSON API does not allow direct properties on relationships, the disposition is stored in the relationship metadata.
Updating and Deleting All Relationships
To replace all existing relationships between and Asset and some Topics, PATCH the endpoint sending the new relationships in the PATCH body. The body is in the same format as when creating a relationship. In JSON API, relationships either exist or do not, so there isn't a mechanism to directly support altering relationship properties of a subset of the relationships. In order to alter the metadata on one or more relationships (e.g. disposition), you must PATCH all relationships including the desired metadata for each relationship. Any relationships or relationship metadata properties NOT included in the PATCH body will be removed. Note that you can remove ALL relationships between Assets and Topics by sending an empty set in the PATCH body. E.g.
Removing Specific Relationships
It is possible to remove specific relationships between an Asset and one or more Topics using the DELETE method and including the Topics relationships to remove from the Asset.
Filtering and Paging Relationships Between Assets and Topics
AB Connect allows you to filter and page through the list of Topics related to an Asset. This can be helpful if you are wanting to limit the Topics you are showing a user to those that have been accepted (for example).
You can filter and sort on relationship properties like meta.disposition or on Topics properties. If you are using Topics properties in your filtering, you are limited to the fields listed in the Topics section of the Filtering Resources by Properties on Related Resources documentation. Note that when using Topics properties for filtering here, you can drop the topics. from the property name.
Fetching Related Topics
Managing Relationships Between Assets and Concepts
If you have licensed the Academic Benchmarks Concept Taxonomy, Concepts enable detailed definition of Asset metadata profiles which power precise search and relationship prediction capabilities. The Asset metadata included describes the Asset with a controlled vocabulary to reflect what should be learned at the most granular level. This level of granular description, combined with machine learning technology, results in an Asset profile that learns from user input, and updates recommendations automatically, facilitating easier change management of Standards. Beyond relationships management, Concepts can be used in your search technologies for advanced and efficient search capabilities.
The process of developing these relationships and describing an Asset with metadata is known as Content Enrichment because by associating an asset with the Academic Benchmark metadata, you gain access to a rich network of additional relationships that can serve to power search and discovery, alignment processes, and navigability within content. When you establish a relationship between a Concept and an Asset, you will notice that the system predictions between the Asset and Standards change and tighten. The Clarifier helps you to tune the system predictions and can be a very powerful addition to your arsenal. See the Clarifier documentation for details.
Here is an easy approach for tagging your Asset with Concepts:
Now if you , you'll see the accepted Standard relationship
Update the predictions made by the system (see ).
Use the Clarifier to Standards and Concepts.
Confirm relationships with Concepts (see below) and/or additional to refine the metadata profile for the Asset
Update the predictions made by the system.
Repeat the clarification steps until the content is fully tagged and predicted relationships are strong.
Note that the context of the Concept is important. Any decisions regarding a relationship between a Concept and an Asset should be made with the context taken into consideration.
Note that use of Academic Benchmarks Assets, Topics, Concepts and Clarifier is enabled through licensing. See the section on Licensing Considerations for a discussion on how to enable these features.
Creating Relationships
You can create (and add) a relationship between an Asset and Concepts by POSTing to /assets/{guid}/concepts. Concepts have different types of relationships with Assets than Topics and Standards. Instead of accepting or rejecting a disposition, Concept relationships have an emphasis of either central, related, not_applicable or avoid. central indicates that the Concept is one of the key notions covered by the Asset. related indicates that the Asset covers the Concept but it is not core to the Asset. not_applicable indicates that the Concept is NOT relevant to the Asset (used to clarify Concepts to aid in predicting relationships). avoid indicates that this Concept is not only irrelevant to the Asset but Standards that relate to this Concept should be avoided when predicting relationships. Since JSON API does not allow direct properties on relationships, the disposition is stored in the relationship metadata.
Updating and Deleting All Relationships
To replace all existing relationships between and Asset and some Concepts, PATCH the endpoint sending the new relationships in the PATCH body. The body is in the same format as when creating a relationship. In JSON API, relationships either exist or do not, so there isn't a mechanism to directly support altering relationship properties of a subset of the relationships. In order to alter the metadata on one or more relationships (e.g. emphasis), you must PATCH all relationships including the desired metadata for each relationship. Any relationships or relationship metadata properties NOT included in the PATCH body will be removed. Note that you can remove ALL relationships between Assets and Concepts by sending an empty set in the PATCH body. E.g.
Removing Specific Relationships
It is possible to remove specific relationships between an Asset and one or more Concepts using the DELETE method and including the Concepts remove from the Asset.
Filtering and Paging Relationships Between Assets and Concepts
AB Connect allows you to filter and page through the list of Concepts related to an Asset. This can be helpful if you are wanting to limit the Concepts you are showing a user to those that are central (for example).
You can filter and sort on relationship properties like emphasis or on Concepts properties. If you are using Concepts properties in your filtering, you are limited to the fields listed in the Concepts section of the Filtering Resources by Properties on Related Resources documentation. Note that when using Concepts properties for filtering here, you can drop the concepts. from the property name.
Fetching Related Concepts
Managing Relationships Between Assets
It is possible to configure the properties of an Asset to allow inter-Asset relationships to be managed. These are very rare use cases. If you have a need to express Asset-to-Asset relationships within AB Connect, start the project with a conversation with AB Support to discuss your use case. AB Support can setup your Asset configuration (asset_type) to allow you to manage these relationships.
AB Connect can support three inter-Asset relationship types:
parent - The parent relationship allows you to build a Asset hierarchy. No additional properties, data or services are conveyed through this relationship. It is simply a means for expressing a hierarchy. Note that there is no reciprocal children property and an Asset can have only one parent.
alignment_donors - Alignment Donors are Assets that convey relationships with Standards and Topics to their Recipients. A Recipient is an Asset that has one or more Assets listed in its alignment_donors relationship. Notes:
Alignment Donor Assets (Assets appearing in an alignment_donor list on some other Asset) can not be deleted. To delete an Alignment Donor, remove it from all alignment_donor relationships and then delete the Asset.
Only Standards and Topics relationships with a disposition of predicted or accepted are conveyed to Recipients.
In the event of disposition conflict in the Donors, accepted takes precedence.
The relationship conveyence is dynamic so changes to Donors are reflected in Recipients. However, if an alignment (relationship to a Standard) is changed on the Alignment Donor, the new alignment will not appear on the Recipient until the Recipient Asset's predictions have been updated.
Standards and Topics relationships can be applied directly to Recipients to augment or override relationships conveyed from Donors.
It is not possible to delete conveyed relationships but it is possible to override them by creating the same relationship directly on the Recipient but setting the disposition to rejected.
concept_donors - Concept Donors are Assets that convey relationships with Concepts to their Recipients. A Recipient is an Asset that has one or more Assets listed in its concept_donors relationship. Notes:
Concept Donor Assets (Assets appearing in a concept_donors list on some other Asset) can not be deleted. To delete a Concept Donor, remove it from all concept_donors relationships and then delete the Asset.
Creating Relationships
You can create (and add) a relationship between Assets by POSTing to /assets/{guid}/{relationship}. Parent relationships are single entities. The others must be arrays.
Alignment Donors
Concept Donors
Updating and Deleting All Relationships
To replace all existing relationships between an Asset and its alignment_donors or concept_donors, PATCH the endpoint sending the new relationships in the PATCH body. The body is in the same format as when creating a relationship. In order to alter the relationships with PATCH, you must include all relationships you'd like to retain in the request. Any relationships of this type that are NOT included in the PATCH are removed. Note that you can remove ALL relationships between Assets and Concepts by sending an empty set in the PATCH body. E.g.
Alignment Donors
Concept Donors
Removing Specific Relationships
It is possible to remove specific relationships between a Assets using the DELETE method and including the Assets to remove.
Alignment Donors
Concept Donors
Generating Predictions
The Predictions endpoint allows you to predict relationships between unrelated entities. AB Connect currently supports three prediction scenarios:
Predict Standards alignments and Topics for an Asset based on the metadata description of the Asset and machine learning algorithms
Predict Standards alignments for an Asset based on Crosswalk relationships
Predict Assets that would align to a Standard based on Crosswalk relationships
Note that access to Predictions is licensed. If your credentials are correct and you are still receiving a 401 error (or no results), check with AB Support to ensure you are licensed for Predictions. See the section on Licensing Considerations for a discussion on the licensing required for access to Predictions.
Working with Predictions for an Asset is implemented as follows:
Predicting Assets for Standards is implemented as follows:
Calculating the Latest Predictions
Using the POST method, you can generate a set of predictions for the specified scenario. Calculating Predictions does not create relationships. It just calculates what relationships appear to be relevant. The relationships can be established as a later step. There are two algorithms for generating Predictions: machine learning and crosswalk relationships.
Machine Learning The machine learning algorithm for predicting relationships is called the "confidence" algorithm. At this point, confidence can only be used to predict Standards and Topics alignments for Assets. Attempting to use confidence to predict Assets for a Standard will result in an error. The Topics relationships are predicted based on the established relationships between the Topics and Standards already aligned to the Asset. Standards relationships are predicted based on the metadata definition of the Asset which includes alignments to other Standards, Topics, Concepts, subjects, etc.
Crosswalks When Crosswalks are used for prediction purposes, they represent two corners of a triangle, with an asset providing the third corner. Using existing alignments (and traversing the edges of the triangle), the system provides predictions of both new standards to assets as well as unaligned assets to new standards. This algorithm uses the Crosswalk relationships between Standards to identify additional relevant Standards. In the case of predicting related Assets, the system walks the Standards relationships and identifies Assets related to the connected Standards.
Note that the Crosswalk relationships are available directly to the calling application through the Standards endpoint, but the predictor simplifies use by navigating common relationships to generate Crosswalks between documents that aren't directly related. E.g. if you are attempting to predict from an Indiana Standard to a New Jersey Standard and Academic Benchmarks has not directly curated relationships between those documents, the predictor will use an intermediary document (perhaps one in Texas) to synthesize the relationships for the predictions. Note that the steps the system had to take to establish the prediction is available in the steps property. Predictions with 1 step are from directly connected Standards. Predictions with 2 are generated by walking from one authority to a common document then to the second authority. In this case, the relationships may lose some precision.
Usage Sometimes calculating Predictions can be resource intensive and take several seconds or even a few minutes. For this reason, the Predictions endpoint uses a queue model. The request to calculate Predictions returns a queue-status object. The queue-status object indicates the state of the queued processing of Predictions. If the calculations complete quickly (less than 30 seconds), the request response will indicate that the calculations are complete and you can GET the Predictions right away. If the calculations go beyond 30 seconds, the response will indicate that the calculations are continuing in which case you will need to check the queue periodically until you receive a response indicating that the calculations are complete. See Fetching the Prediction Queue Status for details on polling the queue.
Note that both the queue-status and predictions objects have GUIDs that are different from the related Asset GUID. If you are checking the queue status, use the links.self URL or construct the URL manually using the GUID in the data.id property. Similarly, once the predictions are complete, use the relationships.predictions.links.related property to locate the predicted alignments.
Checking the Prediction Queue Status
The Queue Status endpoint allows you to check on the Predictions calculations progress for long running Predictions.
Fetching the Queue Status
Using the GET method, you can retrieve the queue-status and check the data.attributes.code field. pending means the Predictions are still being calculated. complete means the Predictions are ready. See the data.relationships.predictions.links.related property for a link to the results.
Retrieving Predictions
The Predictions endpoint allows you to retrieve the details of the Prediction set (like when it expires, what Asset it is related to) and start paging through predicted relationships.
Note that access to Predictions is licensed. If your credentials are correct and you are still receiving a 401 error (or no results), check with AB Support to ensure you are licensed for Predictions. See the section on Licensing Considerations for a discussion on the licensing required for access to Predictions.
Fetching the Predictions
Using the GET method, you can see what predictions the engine makes for the Asset metadata profile using the GUID or related URL (relationships.predictions.links.related) returned when calculating the predictions.
Filtering and Paging Predictions
AB Connect allows you to filter and page through predicted standards. You can filter and sort on relationship properties like meta.score or on the item properties themselves.
Fetching Related Standards
Fetching Related Topics
Updating Predictions on the Asset
To commit the Predictions to the Asset as alignments, POST to the predictions/assets endpoint supplying the Predictions GUID. This updates the predicted alignments on the Asset, replacing any previously predicted alignments and creating new deleted_alignments as appropriate.
Updating Predictions on the Asset
Note that the POST has no request nor response body.
Request a Clarification
One key component to the prediction engine is the Clarifier which can be used on an Asset to request Concepts and Standards for which the system needs clarification regarding the status of the relationship between the Asset and Concepts/Standards. As the user provides input about clarifications, the system refines its calibration for the ranking of Asset-Standards relationship predictions. The Clarifier, combined with setting the disposition of Standards and the emphasis of Concepts, helps the user build an Asset profile that continues to learn and adapt as input is provided, making search capabilities stronger and relationship maintenance far simpler.
To retrieve clarifications for an Asset, call the Clarifier endpoint appending the AB GUID of the Asset in question to the path portion of the URL. If you do not know the AB GUID for the Asset in question, you can search the Asset endpoint filtering on the client_id which should be your ID for the Asset. See the section on Assets for details on searching for Assets.
Note that access to the Clarifier is controlled by licensing. If your credentials are correct and you are still receiving a 401 error (or no results), check with AB Support to ensure you are licensed for the Clarifier. See the section on Licensing Considerations for a discussion on the licensing required for access to the Clarifier.
Fetching a Clarification
Filtering and Paging Relationships on Standards
AB Connect allows you to filter and page through related objects. You can filter and sort on relationship properties like meta.same_text or, in the case of Concepts, descr or context.
Fetching Related Standards
Fetching Related Topics
Fetching Related Concepts
Filtering and Paging Relationships on Topics
AB Connect allows you to page through objects related to the Topic. Filtering the list of related objects is not supported at this point in time.
Fetching Related Objects
How To Articles, Recommendations and Suggestions
How to Navigate the Standards Organizational Structure
Standards are organized hierarchically under authorities. An authority is an organization that has defined a set of academic Standards (e.g. Alabama DOE or NGA Center/CCSSO). Authorities have groups of Standards that we refer to as publications. Publications typically cover multiple subject areas. An example of a publication is New York's Next Generation Learning Standards. It covers both math and ELA. Within a publication, we organize Standards into documents based on subject and adoption year. So within New York's Next Generation Learning Standards, one of the documents is Mathematics 2017. Each document is organized into sections. A section is a group in the document that covers the Standards for a particular set - typically a grade (e.g. 2nd Grade) or course (e.g. Algebra II). Once you've gotten to the section level, the rest of the data is organized into a hierarchical structure of the Standards by level and are related by parent/child relationships. Let's walk through an example:
Calendar Events
Welcome to Our New API Docs! This is the new home for all things API (previously at ).
Calendar Events API
API for creating, accessing and updating calendar events.
{
// The URL to the Canvas web UI page for the user's grades, if this is a student
// enrollment.
"html_url": "",
// The user's current grade in the class. Only included if user has permissions
// to view this grade.
"current_grade": "",
// The user's final grade for the class. Only included if user has permissions
// to view this grade.
"final_grade": "",
// The user's current score in the class. Only included if user has permissions
// to view this score.
"current_score": "",
// The user's final score for the class. Only included if user has permissions
// to view this score.
"final_score": "",
// The total points the user has earned in the class. Only included if user has
// permissions to view this score and 'current_points' is passed in the
// request's 'include' parameter.
"current_points": 150,
// The user's current grade in the class including muted/unposted assignments.
// Only included if user has permissions to view this grade, typically teachers,
// TAs, and admins.
"unposted_current_grade": "",
// The user's final grade for the class including muted/unposted assignments.
// Only included if user has permissions to view this grade, typically teachers,
// TAs, and admins..
"unposted_final_grade": "",
// The user's current score in the class including muted/unposted assignments.
// Only included if user has permissions to view this score, typically teachers,
// TAs, and admins..
"unposted_current_score": "",
// The user's final score for the class including muted/unposted assignments.
// Only included if user has permissions to view this score, typically teachers,
// TAs, and admins..
"unposted_final_score": "",
// The total points the user has earned in the class, including muted/unposted
// assignments. Only included if user has permissions to view this score
// (typically teachers, TAs, and admins) and 'current_points' is passed in the
// request's 'include' parameter.
"unposted_current_points": 150
}
{
// The ID of the enrollment.
"id": 1,
// The unique id of the course.
"course_id": 1,
// The SIS Course ID in which the enrollment is associated. Only displayed if
// present. This field is only included if the user has permission to view SIS
// information.
"sis_course_id": "SHEL93921",
// The Course Integration ID in which the enrollment is associated. This field
// is only included if the user has permission to view SIS information.
"course_integration_id": "SHEL93921",
// The unique id of the user's section.
"course_section_id": 1,
// The Section Integration ID in which the enrollment is associated. This field
// is only included if the user has permission to view SIS information.
"section_integration_id": "SHEL93921",
// The SIS Account ID in which the enrollment is associated. Only displayed if
// present. This field is only included if the user has permission to view SIS
// information.
"sis_account_id": "SHEL93921",
// The SIS Section ID in which the enrollment is associated. Only displayed if
// present. This field is only included if the user has permission to view SIS
// information.
"sis_section_id": "SHEL93921",
// The SIS User ID in which the enrollment is associated. Only displayed if
// present. This field is only included if the user has permission to view SIS
// information.
"sis_user_id": "SHEL93921",
// The state of the user's enrollment in the course.
"enrollment_state": "active",
// User can only access his or her own course section.
"limit_privileges_to_course_section": true,
// The unique identifier for the SIS import. This field is only included if the
// user has permission to manage SIS information.
"sis_import_id": 83,
// The unique id of the user's account.
"root_account_id": 1,
// The enrollment type. One of 'StudentEnrollment', 'TeacherEnrollment',
// 'TaEnrollment', 'DesignerEnrollment', 'ObserverEnrollment'.
"type": "StudentEnrollment",
// The unique id of the user.
"user_id": 1,
// The unique id of the associated user. Will be null unless type is
// ObserverEnrollment.
"associated_user_id": null,
// The enrollment role, for course-level permissions. This field will match
// `type` if the enrollment role has not been customized.
"role": "StudentEnrollment",
// The id of the enrollment role.
"role_id": 1,
// The created time of the enrollment, in ISO8601 format.
"created_at": "2012-04-18T23:08:51Z",
// The updated time of the enrollment, in ISO8601 format.
"updated_at": "2012-04-18T23:08:51Z",
// The start time of the enrollment, in ISO8601 format.
"start_at": "2012-04-18T23:08:51Z",
// The end time of the enrollment, in ISO8601 format.
"end_at": "2012-04-18T23:08:51Z",
// The last activity time of the user for the enrollment, in ISO8601 format.
"last_activity_at": "2012-04-18T23:08:51Z",
// The last attended date of the user for the enrollment in a course, in ISO8601
// format.
"last_attended_at": "2012-04-18T23:08:51Z",
// The total activity time of the user for the enrollment, in seconds.
"total_activity_time": 260,
// The URL to the Canvas web UI page for this course enrollment.
"html_url": "https://...",
// The URL to the Canvas web UI page containing the grades associated with this
// enrollment.
"grades": {"html_url":"https:\/\/...","current_score":35,"current_grade":null,"final_score":6.67,"final_grade":null},
// A description of the user.
"user": {"id":3,"name":"Student 1","sortable_name":"1, Student","short_name":"Stud 1"},
// The user's override grade for the course.
"override_grade": "A",
// The user's override score for the course.
"override_score": 99.99,
// The user's current grade in the class including muted/unposted assignments.
// Only included if user has permissions to view this grade, typically teachers,
// TAs, and admins.
"unposted_current_grade": "",
// The user's final grade for the class including muted/unposted assignments.
// Only included if user has permissions to view this grade, typically teachers,
// TAs, and admins..
"unposted_final_grade": "",
// The user's current score in the class including muted/unposted assignments.
// Only included if user has permissions to view this score, typically teachers,
// TAs, and admins..
"unposted_current_score": "",
// The user's final score for the class including muted/unposted assignments.
// Only included if user has permissions to view this score, typically teachers,
// TAs, and admins..
"unposted_final_score": "",
// optional: Indicates whether the course the enrollment belongs to has grading
// periods set up. (applies only to student enrollments, and only available in
// course endpoints)
"has_grading_periods": true,
// optional: Indicates whether the course the enrollment belongs to has the
// Display Totals for 'All Grading Periods' feature enabled. (applies only to
// student enrollments, and only available in course endpoints)
"totals_for_all_grading_periods_option": true,
// optional: The name of the currently active grading period, if one exists. If
// the course the enrollment belongs to does not have grading periods, or if no
// currently active grading period exists, the value will be null. (applies only
// to student enrollments, and only available in course endpoints)
"current_grading_period_title": "Fall Grading Period",
// optional: The id of the currently active grading period, if one exists. If
// the course the enrollment belongs to does not have grading periods, or if no
// currently active grading period exists, the value will be null. (applies only
// to student enrollments, and only available in course endpoints)
"current_grading_period_id": 5,
// The user's override grade for the current grading period.
"current_period_override_grade": "A",
// The user's override score for the current grading period.
"current_period_override_score": 99.99,
// optional: The student's score in the course for the current grading period,
// including muted/unposted assignments. Only included if user has permission to
// view this score, typically teachers, TAs, and admins. If the course the
// enrollment belongs to does not have grading periods, or if no currently
// active grading period exists, the value will be null. (applies only to
// student enrollments, and only available in course endpoints)
"current_period_unposted_current_score": 95.8,
// optional: The student's score in the course for the current grading period,
// including muted/unposted assignments and including ungraded assignments with
// a score of 0. Only included if user has permission to view this score,
// typically teachers, TAs, and admins. If the course the enrollment belongs to
// does not have grading periods, or if no currently active grading period
// exists, the value will be null. (applies only to student enrollments, and
// only available in course endpoints)
"current_period_unposted_final_score": 85.25,
// optional: The letter grade equivalent of
// current_period_unposted_current_score, if available. Only included if user
// has permission to view this grade, typically teachers, TAs, and admins. If
// the course the enrollment belongs to does not have grading periods, or if no
// currently active grading period exists, the value will be null. (applies only
// to student enrollments, and only available in course endpoints)
"current_period_unposted_current_grade": "A",
// optional: The letter grade equivalent of current_period_unposted_final_score,
// if available. Only included if user has permission to view this grade,
// typically teachers, TAs, and admins. If the course the enrollment belongs to
// does not have grading periods, or if no currently active grading period
// exists, the value will be null. (applies only to student enrollments, and
// only available in course endpoints)
"current_period_unposted_final_grade": "B"
}
POST Predictions to start the calculation process
if queue-status Response has code pending
loop until queue-status has code complete
GET queue-status with max_wait=25
endloop
if you want to review Predictions, GET Predictions and page/filter through them
POST to Predictions/Asset to update Predictions on Asset
POST Predictions to start the calculation process
if queue-status Response has code pending
loop until queue-status has code complete
GET queue-status with max_wait=25
endloop
Review Predictions, GET Predictions and page/filter through them
Determine which Assets should get alignments to the standard in question
POST new alignments to those Assets
state[]
string
Filter by enrollment state. If omitted, ‘active’ and ‘invited’ enrollments are returned. The following synthetic states are supported only when querying a user’s enrollments (either via user_id argument or via user enrollments endpoint): current_and_invited, current_and_future, current_future_and_restricted, current_and_concluded
Array of additional information to include on the enrollment or user records. “avatar_url” and “group_ids” will be returned on the user record. If “current_points” is specified, the fields “current_points” and (if the caller has permissions to manage grades) “unposted_current_points” will be included in the “grades” hash for student enrollments.
Filter by user_id (only valid for course or section enrollment queries). If set to the current user’s id, this is a way to determine if the user has any enrollments in the course or section, independent of whether the user has permission to view other people on the roster.
grading_period_id
integer
Return grades for the given grading_period. If this parameter is not specified, the returned grades will be for the whole course.
enrollment_term_id
integer
Returns only enrollments for the specified enrollment term. This parameter only applies to the user enrollments path. May pass the ID from the enrollment terms api or the SIS id prepended with ‘sis_term_id:’.
sis_account_id[]
string
Returns only enrollments for the specified SIS account ID(s). Does not look into sub_accounts. May pass in array or string.
sis_course_id[]
string
Returns only enrollments matching the specified SIS course ID(s). May pass in array or string.
sis_section_id[]
string
Returns only section enrollments matching the specified SIS section ID(s). May pass in array or string.
sis_user_id[]
string
Returns only enrollments for the specified SIS user ID(s). May pass in array or string.
created_for_sis_id[]
boolean
If sis_user_id is present and created_for_sis_id is true, Returns only enrollments for the specified SIS ID(s). If a user has two sis_id’s, one enrollment may be created using one of the two ids. This would limit the enrollments returned from the endpoint to enrollments that were created from a sis_import with that sis_user_id
enrollment[user_id]
Required string
The ID of the user to be enrolled in the course.
enrollment[type]
Required string
Enroll the user as a student, teacher, TA, observer, or designer. If no value is given, the type will be inferred by enrollment[role] if supplied, otherwise ‘StudentEnrollment’ will be used.
If set to ‘active,’ student will be immediately enrolled in the course. Otherwise they will be required to accept a course invitation. Default is ‘invited.’.
If set to ‘inactive’, student will be listed in the course roster for teachers, but will not be able to participate in the course until their enrollment is activated.
Allowed values: active, invited, inactive
enrollment[course_section_id]
integer
The ID of the course section to enroll the student in. If the section-specific URL is used, this argument is redundant and will be ignored.
enrollment[limit_privileges_to_course_section]
boolean
If set, the enrollment will only allow the user to see and interact with users enrolled in the section given by course_section_id.
For teachers and TAs, this includes grading privileges.
Section-limited students will not see any users (including teachers and TAs) not enrolled in their sections.
Users may have other enrollments that grant privileges to multiple sections in the same course.
enrollment[notify]
boolean
If true, a notification will be sent to the enrolled user. Notifications are not sent by default.
enrollment[self_enrollment_code]
string
If the current user is not allowed to manage enrollments in this course, but the course allows self-enrollment, the user can self- enroll as a student in the default section by passing in a valid code. When self-enrolling, the user_id must be ‘self’. The enrollment_state will be set to ‘active’ and all other arguments will be ignored.
enrollment[self_enrolled]
boolean
If true, marks the enrollment as a self-enrollment, which gives students the ability to drop the course if desired. Defaults to false.
enrollment[associated_user_id]
integer
For an observer enrollment, the ID of a student to observe. This is a one-off operation; to automatically observe all a student’s enrollments (for example, as a parent), please use the User Observees API.
enrollment[sis_user_id]
string
Required if the user is being enrolled from another trusted account. The unique identifier for the user (sis_user_id) must also be accompanied by the root_account parameter. The user_id will be ignored.
enrollment[integration_id]
string
Required if the user is being enrolled from another trusted account. The unique identifier for the user (integration_id) must also be accompanied by the root_account parameter. The user_id will be ignored.
root_account
string
The domain of the account to search for the user. Will be a no-op unless the sis_user_id or integration_id parameter is also included.
enrollment_type
string
Enroll each user as a student, teacher, TA, observer, or designer. If no value is given, the type will be ‘StudentEnrollment’.
In the event of emphasis conflict in the Donors, the order of precedence is central, related, not_applicable and then avoid.
Unlike Alignment Donors, with Concept Donors, Concepts relationships can NOT be applied directly to Concept Recipients.
The relationship conveyence is dynamic so changes to Donors are reflected in Recipients.
If a Concept is added, modified or deleted from a Donor, the Concept relationship change does not show up immediately on the Recipients. In order for the change to propagate to the Recipient, the Recipient has to be modified (be POSTed or PATCHed to) or the Recipient Asset's predictions have been updated.
If a Concept is added, modified or deleted from a Donor, the relationship predictions on the Recipient are not updated until the Recipient Asset's predictions have been updated.
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
idstringRequired
unique ID for the Standard.
typestring · enumRequired
The type of the referenced object.
Possible values:
dispositionstring · enumRequired
The type of relationship between the Standard and Asset.
Possible values:
itemsstring · enumOptionalPossible values:
Responses
200
OK
application/json
tooknumberOptional
patch
/assets/{guid}/alignments
get
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standards]stringOptional
comma separated list of field names
filter[alignments]stringOptional
an ODATA-like query string used to filter
sort[alignments]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/assets/{guid}/alignments
get
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standards]stringOptional
comma separated list of field names
filter[alignments]stringOptional
an ODATA-like query string used to filter
sort[alignments]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/assets/{guid}/deleted_alignments
patch
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
idstringRequired
unique ID for the Standard.
typestring · enumRequired
The type of the referenced object. Literally "standards".
Possible values:
dispositionstring · enumRequired
The type of relationship between the Standard and Asset.
Possible values:
Responses
200
OK
application/json
tooknumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
409
Conflict
application/json
patch
/assets/{guid}/topics
get
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[topics]stringOptional
comma separated list of field names
filter[topics]stringOptional
an ODATA-like query string used to filter
sort[topics]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/assets/{guid}/topics
patch
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
idstringRequired
The unique identifier for this Concept. This can be used with the Concepts endpoint to retrieve a description and context.
typestring · enumRequired
Literal "concepts" - this field is a JSON API requirement.
Possible values:
emphasisstring · enumRequired
The type of relationship between the Concept and Asset.
Possible values:
Responses
200
OK
application/json
tooknumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
409
Conflict
application/json
patch
/assets/{guid}/concepts
get
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[concepts]stringOptional
comma separated list of field names
filter[concepts]stringOptional
an ODATA-like query string used to filter
sort[concepts]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/assets/{guid}/concepts
get
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[concepts]stringOptional
comma separated list of field names
filter[concepts]stringOptional
an ODATA-like query string used to filter
sort[concepts]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/assets/{guid}/concepts
patch
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
idstringRequired
The unique identifier for this Asset (the GUID).
typestring · enumRequired
Literal "assets" - this field is a JSON API requirement.
Possible values:
Responses
200
OK
application/json
tooknumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
409
Conflict
application/json
patch
/assets/{guid}/alignment_donors
patch
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Body
idstringRequired
The unique identifier for this Asset (the GUID).
typestring · enumRequired
Literal "assets" - this field is a JSON API requirement.
Possible values:
Responses
200
OK
application/json
tooknumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
409
Conflict
application/json
patch
/assets/{guid}/concept_donors
post
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[queue-status]stringOptional
comma separated list of field names
Body
algorithmstring · enumOptional
The prediction algorithm to use; default: "confidence".
Possible values:
idstringRequired
The unique asset identifier.
typestring · enumRequired
Literal "assets" or "standards".
Possible values:
idstringOptional
Unique identifier for this resource.
typestringOptional
Resource type.
Responses
202
Accepted
application/json
400
Bad Request
application/json
401
Authentication Error
application/json
422
Unprocessable content
application/json
post
/predictions
get
Path parameters
guidstringRequired
guid of specified prediction
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[queue-status]stringOptional
comma separated list of field names
max_waitnumberOptional
comma separated list of field names
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
relatedstringOptional
relatedstringOptional
relatedstringOptional
codestring · enumOptional
The code indicating the status of the prediction in the queue.
Possible values:
guidstringOptional
The Queue Status GUID - a duplicate of the id field.
statusstringOptional
A phrase describing the current status of the prediction in the queue.
typestring · enumOptional
Literal "queue-status" - JSON API requirement.
Possible values:
get
/predictions/queue-status/{guid}
get
Path parameters
guidstringRequired
guid of specified prediction set
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[predictions]stringOptional
comma separated list of field names
fields[standards]stringOptional
comma separated list of field names
fields[topics]stringOptional
comma separated list of field names
fields[assets]stringOptional
comma separated list of field names
includestringOptional
A comma separated list of resource names that will be returned in the response.
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
typestringOptional
Literal "predictions" - JSON API requirement.
date_expires_utcstringOptional
The timestamp of the when the prediction set will expire. Predictions tend to be transient in nature so AB Connect does not store them by themselves. If you wish to make the predictions permanent, commit them to the Asset.
guidstringOptional
he Prediction's GUID - a duplicate of the id field.
algorithmstring · enumOptional
The type of prediction being employeed.
Possible values:
date_requested_utcstringOptional
The timestamp of the when the prediction was requested.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
typestringOptional
relatedstringOptional
dataobject[]Optional
relatedstringOptional
typestringOptional
idstringOptional
scorestring · nullableOptional
dispositionstringOptional
stepsnumberOptional
laststringOptional
relatedstringOptional
nextstringOptional
dataobject[]Optional
relatedstringOptional
nextstringOptional
laststringOptional
dataobject[]Optional
relatedstringOptional
nextstringOptional
laststringOptional
idstringOptional
typestringOptional
relatedstringOptional
get
/predictions/{guid}
get
Path parameters
guidstringRequired
guid of specified prediction set
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standards]stringOptional
comma separated list of field names
filter[standards]stringOptional
an ODATA-like query string used to filter
sort[standards]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
get
/predictions/{guid}/standards
get
Path parameters
guidstringRequired
guid of specified prediction set
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[topics]stringOptional
comma separated list of field names
filter[topics]stringOptional
an ODATA-like query string used to filter
sort[topics]stringOptional
a comma separated list of property names specifying the sort order of the returned results
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
get
/predictions/{guid}/topics
post
Path parameters
guidstringRequired
guid of specified prediction set
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
Responses
204
Accepted
post
/predictions/{guid}/asset
204
Accepted
No content
get
Path parameters
guidstringRequired
guid of specified asset
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
includestringOptional
A comma separated list of resource names that will be returned in the response.
fields[clarifier]stringOptional
comma separated list of field names
fields[standards]stringOptional
comma separated list of field names
fields[concepts]stringOptional
comma separated list of field names
filter[clarification_standards]stringOptional
an ODATA-like query string used to filter
Responses
200
OK
application/json
selfstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
idstring · uuidRequired
typestringRequired
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
or
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/clarifier/{guid}
get
Path parameters
guidstringRequired
guid of specified standard
relationshipstring · enumRequired
type of relationship
Possible values:
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[standards]stringOptional
comma separated list of field names
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
typestringOptional
The type of the referenced object.
idstringOptional
Unique ID for the referenced object.
relatedstringOptional
seqnumberOptional
The position of this Standard within this level of the document hierarchy.
captured_bystringOptional
The organization responsible for capturing the Standard in a machine readable format. This is currently hard coded to "AB" but may include other organizations one day.
typestring · enumOptional
Indicates the usage of this Standard.
Possible values:
guidstringOptional
A unique identifier for the utilization.
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
seqnumberOptional
Since there may be multiple addenda, this field specifies the order of the addenda in the list when being place with the statement. The lower the number, the earlier in the list this addendum appears. For example, when assembling the addenda and statements together, it may appear something like addendum1, addendum3, addendum4, statement, addendum2, addendum5. In that example, addenda 1/3/4 would have their position set to "before" and 2/5 are set to "after".
add_contextstring · enumOptional
Indicates if the addendum adds context to the statement and therefore is necessary to fully understand the statement. E.g. "When reading poetry..." adds context while "A student can..." does not.
Possible values:
descrstringOptional
The actual text of the addendum.
positionstring · enumOptional
The location of the addendum with respect to the statement.
Possible values:
combined_descrstringOptional
The main Standard verbiage combined with any decorating text that helps to complete the concept or sentence of the Standard.
descrstringOptional
The main Standard verbiage. It may or may not be a complete sentence or concept on its own.
levelnumberOptional
The level within the document hierarchy in which this Standard appears. Level 1 is the top level. Note that Standards documents often have an inconsistent structure so Standards at the same level can not always be guaranteed to have the same purpose.
date_modified_utcstringOptional
The most recent modification date of this Standard in UTC.
statusstring · enumOptional
The status of the Standard.
Possible values:
symbol_positionstring · enumOptional
Where the symbol falls with respect to the statement line.
Possible values:
symbolstringOptional
The symbol used to indicate the note.
descrstringOptional
The note associated with the symbol.
standard_typestring · enumOptional
This is the purpose of this Standard within the document. This is the AB representation of the type of this particular item. It is often similar in intent to the label field but AB applies a type that is consistent across various documents and authorities.
Possible values:
labelstring · nullableOptional
The authority's label of this Standard in the document. This is often associated with the "level" of this particular line item within the document but given inconsistent document formats and structures, it is more literally tied to the purpose of the line item. E.g. "Benchmark".
descrstringOptional
The strand text.
guidstringOptional
Unique identifier for this strand.
guidstringOptional
Unique identifier.
codestringOptional
An abbreviation for the domain.
descrstringOptional
The domain name.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
codestringOptional
A unique code for the Genre.
guidstringOptional
Unique identifier.
descrstringOptional
The Genre name.
typestring · enumOptional
The type of data stored in the identifier.
Possible values:
sourcestring · enumOptional
The source of the ID. Currently, only "canonical" is supported.
Possible values:
idstringOptional
The actual identifier.
date_deleted_utcstring · nullableOptional
The date this Standard was deleted in UTC.
in_liststring · enumOptional
Indicates that this Standard is part of a list which can be combined with its parent to complete learning objectives. If a Standard has in_list of "Y", its parent has has_list of "Y" also.
Possible values:
guidstringOptional
Unique identifier of the object.
guidstringOptional
A unique ID for this Key Idea
descrstringOptional
The Concept phrase.
guidstringOptional
A unique ID for this Concept.
implementation_yearstringOptional
The year the standards in this document are to be implemented in the classroom.
descrstringOptional
The document name.
date_modified_utcstringOptional
The last modification date of the document in UTC.
source_urlstringOptional
The URL of the source authority's original document.
assessment_yearstring · nullableOptional
The year the standards in this document are to be assessed.
descrstringOptional
Name of the publication.
source_urlstringOptional
The URL of the source authority's original publication.
extended_descrstringOptional
A more readable description of the publication. It typically includes information indicating the authority.
guidstringOptional
A unique identifier for the region.
descrstringOptional
The name of the region.
typestring · enumOptional
An indicator of the type geopolitical boundary the region represents.
Possible values:
codestring · nullableOptional
A unique code for the region. E.g. FL for Florida.
guidstringOptional
A unique identifier for the authority.
descrstringOptional
The authority name. E.g. "Florida DOE" for Florida.
acronymstring · nullableOptional
A brief acronym unique to the authority.
acronymstringOptional
Some authorities have an acronym they commonly use to refer to the Standards document. In those cases, it is captured in this field. E.g. Texas Essential Knowledge and Skills (TEKS) or Florida Sunshine State Standards (SSS). This is not common.
publication_typestring · enumOptional
The type of publication we are working with.
Possible values:
guidstringOptional
Unique identifier for this publication.
guidstringOptional
A unique identifier for this document.
obsolete_yearstring · nullableOptional
The year this document was obsoleted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
adopt_yearstringOptional
The year the standards in this document are to be adopted.
revision_yearstring · nullableOptional
The year this document was last officially revised.
deepeststring · enumOptional
Deepest flag indicates whether the related Standard is the deepest alignable standard.
Possible values:
root_enhancedstringOptional
This field extends the concept of the prefix enhanced number to the full authority and publication description where appropriate. E.g. the prefix enhanced number might be something like "MA.8.16.a.5" while the root enhanced number might look like "OH.AS.MA.8.16.a.5".
enhancedstringOptional
This field is the raw number enhanced to indicate the complete hierarchy of the raw number in the cases where an authority does not carry the hierarchical numbering through directly themselves. E.g. if the "raw" is "5", the enhanced would be something like "16.a.5".
prefix_enhancedstringOptional
This field extends the concept of the enhanced number to the full subject and grade description where appropriate. E.g. if the "enhanced" number is "16.a.5", the prefix enhanced number might be something like "MA.8.16.a.5" if the Standard is in 8th grade math.
rawstring · nullableOptional
The literal number and formatting included in the Standard document next to this particular Standard. Note that in most cases it is a number without context like "5". However, it may have hierarchical numbering (and associated separators) with it as well. E.g. "16.a 5".
alternatestring · nullableOptional
An alternate number schema that is familiar to users of the standards. This will only exist in scenarios where this familiar, often shortened, number does not match the existing built-out enhanced options. E.g. in Common Core raw number might look like "a", enhanced number might be something like "CCSS.Math.Content.1.NBT.B.2.a" while alternate number would be "1.NBT.B.2.a".
guidstringOptional
Unique identifier for the age.
descrstringOptional
Label for the age - typically the number of the age (in months). E.g. 6 indicates 6 months.
seqnumberOptional
The order this age appears in the list of ages.
guidstringOptional
Unique identifier for the grade.
descrstringOptional
The name of the grade. E.g. 3rd Grade.
codestringOptional
An abbreviation for the grade - typically the grade number. E.g. 3 for 3rd grade, K for Kindergarten
seqnumberOptional
The order this grade appears in a list of grades.
guidstringOptional
A unique identifier for this section.
seqnumberOptional
A number indicating the order this section falls within the document.
date_modified_utcstringOptional
The date of the latest modification to the section in UTC.
descrstringOptional
The name of the section.
implementation_yearstringOptional
The year the standards in this section are to be implemented in the classroom.
numberstring · nullableOptional
The authority number for the section. This is not common.
assessment_yearstring · nullableOptional
The year the standards in this section are to be assessed.
revision_yearstring · nullableOptional
The year this section was last officially revised.
labelstring · nullableOptional
The authority's label of this section in the document. An example would be the Conceptual Categories in Common Core.
obsolete_yearstring · nullableOptional
The year this section was obsoleted.
adopt_yearstringOptional
The year this section was adopted.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
typestring · enumOptional
The type of this extension. Note that, historically, Academic Benchmarks included all extensions as one block of text per Standard and did not capture the type of the extension. These extensions will be returned via the API with a type "unknown".
Possible values:
guidstringOptional
The unique ID for this extension.
descrstringOptional
The text of the extension.
has_liststringOptional
Indicates that this Standard line item is a parent of a list of line items. This is often used when a Standard is incomplete in itself and is the opening statement of a list of specific details. E.g. this Standard may say something like "Student can calculate the area of:" and the children Standards might be "Triangle", "square", "circle". If "Y", this Standard can be combined with its children to make individual specific learning objectives.
topic_organizerstring · nullableOptional
The use of this field has been deprecated so it will only contain a value for older Standards. In those cases, when there was a title, topic, term or short phrase associated to many Standards but did not actually appear in the hierarchy of the document, we would capture it as an organizer in this field for the Standards to which it applied. In recent history and moving forward, this would be inserted into the hierarchy as a separate Standard.
idstringOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/standards/{guid}/{relationship}
get
Path parameters
guidstringRequired
guid of specified standard
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[topics]stringOptional
comma separated list of field names
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
typestringOptional
Synonym for our GUID field required by the JSON API standard.
idstringOptional
Literal "topics" - JSON API requirement.
idstringOptional
typestringOptional
relatedstringOptional
idstringOptional
typestringOptional
relatedstringOptional
laststringOptional
relatedstringOptional
nextstringOptional
idstringOptional
typestringOptional
date_modified_utcstringOptional
The most recent modification date of this Topic in UTC.
descrstringOptional
codestringOptional
guidstringOptional
statusstring · enumOptional
The status of the Topic.
Possible values:
guidstringOptional
Unique identifier of the object.
date_modified_utcstringOptional
guidstringOptional
revision_yearstringOptional
adopt_yearstringOptional
descrstringOptional
seqnumberOptional
The position of this Topic within this level of the document hierarchy.
levelnumberOptional
The level within the document hierarchy in which this Topic appears. Level 1 is the top level. Note that Topics documents only have two levels of depth.
descrstringOptional
date_modified_utcstringOptional
seqnumberOptional
guidstringOptional
uristringOptional
The URI of this resource. Note that this differs from the JSON API "self" in the "links" section of the response in that it does not include any arguments that were included in the request.
descrstringOptional
The text of the Topic.
descrstringOptional
guidstringOptional
codestringOptional
seqnumberOptional
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/standards/{guid}/topics
get
Path parameters
guidstringRequired
guid of specified standard
Query parameters
partner.idstringRequired
Your partner ID - you should have gotten them from AB Support or when you signed up for a sandbox account.
auth.signaturestringRequired
Signature for the request authorization.
auth.expiresstringRequired
Expiration timestamp for the authorization.
fields[concepts]stringOptional
comma separated list of field names
limitnumberOptional
The page size for the response dataset. limit must be 100 or less.
offsetnumberOptional
How far into the dataset you are paging
Responses
200
OK
application/json
selfstringOptional
firststringOptional
laststringOptional
nextstringOptional
prevstringOptional
tooknumberOptional
Duration of server side request processing in milliseconds.
limitnumberOptional
The array pagination page size for the request.
countnumberOptional
The array size for pagination (max count).
offsetnumberOptional
The array pagination offset for the request.
descrstringOptional
The text of the Concept.
codestringOptional
An abbreviation for the subject.
descrstringOptional
The subject text.
guidstringOptional
Unique identifier for this subject.
guidstringOptional
Unique identifier of the object.
contextstringOptional
The hierarchy of the Concept represented as a string with each level separated by a >. The context is an extremely important part of the Concept definition. It is critical that decisions around the applicability and use of a Concept include the context.
idstringOptional
Synonym for our GUID field required by the JSON API standard.
typestringOptional
Literal "concepts" - JSON API requirement.
400
Bad Request
application/json
401
Authentication Error
application/json
404
Entity not found
application/json
get
/standards/{guid}/concepts
First, to retrieve a list of authorities in your license, use faceting and list the authorities (document.publication.authorities). E.g.:
The results from that call will include a set of authority facets in the meta.facet part of the JSON. For this example, let's look at the New York Standards.
Now that you have the GUID for the New York DOE authority, you can use that to narrow your focus to NY and request publications.
We'll pick the Next Generation Learning Standards and look at the documents.
Let's take that publication GUID and look for related documents.
Let's focus on the math document.
With the math document GUID, you can list the related sections.
Let's look at the Algebra II section.
Now we are ready to start to navigate the Standards. To start that process, look for Standards in the Algebra II section. The Standards are organized in a hierarchy but are not necessarily returned in that order so limit the response to the top level of the hierarchy and sort by the sequence so you are reproducing the section as a user would expect to see it. If you are using these calls to build a tree in a UI, you may want to request the children property be included in the response so your front-end code can decide whether or not to add an icon to allow the browser to expand this Standard to show its children. I'll leave it out of this example so I don't clutter the data response, but you could include that information using a fields parameter in the URL like: fields[standards]=seq,number,statement,children.
We'll ignore data paging here and assume that you can manage that part. Looking at the results, there are only a couple of branches at this level. We've simplified the data here to make it easier to read:
Now that we have the top level of Standards, we need to look at the children Standards. We'll start with the Operations and Algebraic Thinking branch and look for its children by searching for Standards that have this particular Standard as a parent. Again, we are sorting by the sequence order.
The results look something like the data below (again simplifying the response for clarity).
Now you can repeat that process for each Standard in this list - searching for Standards that have each of these as parents - until you reach the bottom of the hierarchy. As you do this, there are a few things to keep in mind:
Most documents are not consistent in the number of levels they have. The bottom level is often the level that represents a single learning objective but sometimes the bottom is an example and the level above is the objective.
Check the utilization.type of a Standard to validate its usage. alignable Standards are the learning objectives. These typically have Key Ideas, Topics and Concepts associated with them.
Special Considerations When Rendering Standards In User Interfaces
Representing Standards As Chips
A common modern user interface element in selection scenarios is the "chip". A chip is a compact element that typically represents a more complex object in a tight space. If you are not familiar with chips, you can see examples on the Material Design site. The dominant attribute of chips is compactness. For this reason, the representation of a Standard as a chip is challenging. We find that using the enhanced (or pre-fix enhanced) number is the best representation of a standard on a chip combined with hover text or an info icon to allow the user to easily find a more complete definition of the Standard.
Be aware that numbers are not guaranteed to be unique and some Standards do not have numbers. When working with Standards that aren't numbered, you may want to fallback to showing the first 10-15 characters of the text. While that is not likely to be too informative, when you combine it with the ability to see more details about the standard, it should be enough for a user to understand its usage.
Handling Standards That Have Lists and Addenda
Standards with addenda with position set to after that have has_list set to Y are very rare, but they do occur periodically, and the rendering requires special treatment. In this case, addenda with position set to after should be displayed after the list of items. The final rendering is determined by your application, but here is an example and two likely renderings.
Statement: Determine the equation of a linear relation, given:
Before Addendum: It is expected that students will:
After Addendum: to solve problems.
Child List Standards:
a graph
a point and the slope
two points
a point and the equation of a parallel or perpendicular line
Working With Deleted Standards
Standards are occasionally deleted when the authority makes changes that impact the intent of the Standard. When this happens, the Standard is deleted and the related GUID is "retired" so the integrity of related alignments is not tarnished by a change in the intent of the Standard. You can still access these Standards via AB Connect but there are a couple of things to keep in mind:
When looking up a standard by GUID (https://api.abconnect.instructure.com/rest/v4.1/standards/<GUID>), the system will respond with the standard regardless of whether it is deleted or not.
When filtering Standards, deleted Standards are excluded from filter results unless the filter criteria explicitly includes Standards with deleted status. E.g. status EQ 'deleted' or status IN ('active','deleted')
AB Connect tracks deleted Standards back to January 2008. Due to the evolution of the AB Connect data model, the amount of metadata available on deleted standards varies over time. Standards deleted in January 2008 have less metadata than modern standards.
How To Populate Your Local Cache With AB Connect Data
Many AB Connect customers cache the data locally to support analytics and other operations that require performant combination of AB Connect data with local data. This article discusses the options for downloading that initial cache.
The first consideration is when your v4.1API access was enabled vs. when you became an Academic Benchmarks partner. If you are a new partner, the easiest approach is to implement use of the Events endpoint and start with seq GT 0. This will download all events as each document is added to your license and you can use these events to populate your local cache. See Using Events As A New Partner in the Events documentation for more details.
However, if you were a partner before v4.1was enabled for your account (or you became a customer before November 2018), the initial events to add documents to your license don't exist. In that case, a common approach is to have your system Navigate the Standards Organizational Structure and cache the Standards as the system walks the structure.
How To Efficiently Update Your Local Cache With The Latest AB Connect Data
Many Academic Benchmarks partners opt to take advantage of AB Connect's fast search architecture to directly power their system search, standards and alignment activities while others prefer to cache the data locally. If you cache data, AB Connect has solutions that make updates and workflows like alignment maintenance efficient.
Standards Updates
Standards evolve over time. Authorities frequently make minor changes to individual standards and periodically adopt new documents that replace existing standards. When a new document is adopted, it may be added to your standards delivery. Either way, 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. You can read more about Events and keeping your cache current in the section on the Events endpoint.
Alignment Updates
As standards evolve and your content library changes and expands, you will need to update your local storage of alignments. See the paragraph titled "Locating Recent Changes to Relationships Between Assets and Standards" in the Managing and Predicting Relationships section for information on retrieving alignment changes.
Asset Updates
If AB Connect is the system of truth for your content's metadata profiles, you can update your cache by locating and retrieving modified Assets. The following filter returns assets updated since September 2018.
How To Map Alignments From One Document To Another
Content publishers often partner with Academic Benchmarks as they expand their offerings by bringing content to new market segments and geographies through alignment to new standards. With such expansion, many publishers experience the challenge of aligning content and maintaining alignments across multiple states and authorities. AB Connect offers a wide array of metadata and functionality to assist. There are a couple of approaches you can take using AB Connect to address this challenge.
Relationships
AB Connect includes standards relationships, which allow publishers to leverage existing standards alignments and expedite alignment of content from one authority to another, or across multiple states and markets segments. The advantage of this approach is a degree of automation that can drastically reduce the number of correlations that need to be hand reviewed.
Crosswalks
Some standards documents have direct relationships to other documents - either historical (2021 document replaces the 2017 document) or from other authorities (a state derives its standards from the Common Core). For documents without a data relationship or a state published relationship to other standards, Academic Benchmarks subject matter experts curate a crosswalk relationship. E.g. Texas standards are not related to the Common Core. Academic Benchmarks curates relationships between various documents and captures the relationships in the Crosswalks field.
Standards related as Crosswalks share at least one skill. Crosswalks are based on close relationships where they are established by the authority and hand curation where they are not. Not all documents are directly crosswalked to every other document. At the time of the writing of this documentation, math, science and ELA in the US should all be mapped to at least one common document but the scope of coverage in subjects and regions will continue to expand. You can use the predictions endpoint to help get Crosswalks between documents that are not directly connected. See Generating Predictions for details.
Note that Crosswalks are not available on all accounts. See the section on Licensing Considerations for a discussion on the licensing required for access to Crosswalks.
Derivatives
If your content is aligned to a national document, you can use the Derivatives Relationship on the national standards to locate standards in a derived document - E.g. Common Core Math to California Common Core Content Standards.
Derivatives carry two key pieces of metadata to assist with automation: "same text" and "same Concepts." The former is true ("Y" in the API data model) if the standard in the national document is character for character the same as the standard in the derived document. The latter is true if the standard in the national document covers the same concepts. Derivatives with the same text and concepts can typically be automatically mapped to content. Most organizations automatically map derivatives with same concepts as well, but we recommend making that decision in coordination with your editorial team.
Notes:
In many cases, an authority will clearly state that their Standards are derived from a national document but in cases where they disclaim derivation but are very closely modeled after the national document, AB Connect still exposes derivative relationships.
While a Standard will often have a 1:1 mapping with a Standard in a derived state, it is possible that there are multiple Standards derived from the single national Standard. This typically happens when a state breaks out a compound Standard into multiple, more specific Standards.
There are relationships where the Standards have the same text but same Concepts is N. This occurs when a state has limited or otherwise changed the intent of the Standard through verbiage found in the hierarchical parentage of the Standard.
Origins
If your content is aligned to a derived document and you want to map to the national document, the Origins Relationship helps you do that - E.g. Georgia Standards of Excellence ELA to Common Core ELA. It is the inverse of the derivatives relationship. The approach and metadata are the same as that described above in the Derivatives section. Note that just as there may be multiple standards derived from one national standard, it is possible that a derived standard is a combination of multiple origin standards.
Peer Derivatives
If your content is aligned to a derived document and you want to map to another state document derived from the same origin, you can use the Peer Derivatives Relationship. Peer derivatives are related through a common Origin Standard. An example of this relationship includes two states that have adopted the Common Core State Standards. The approach and metadata are largely the same as that of origins and derivatives but there is one caveat: the "same text" and "same concepts" metadata on the peer derivatives is with respect to the origin - not the standard you are starting from. In order to be confident that the existing alignment equates with an alignment to the new destination, both the origin AND the peer derivative same text (and/or same concepts) flags should be true. If the origin same text is Y but the peer derivative is N, then the text of the Standard you are starting with is not the same as the text of the peer derivative.
Peers
Derivatives, origins and peer derivatives are great where they exist, but how do you handle mapping alignments to non-derived authorities (e.g. Common Core to Texas) or where there is no derivative, origin or peer derivative in the destination document? Two additional relationships are provided between these documents: Peers and Crosswalks. This section gives an overview of Peers. See the above section for more details on Crosswalks.
Peers are standards that are related through alignments to common educational resources. These standards are crowd sourced from curated, targeted, resources. Due to the nature of peers, editorial staff typically review the system suggestions for applicability for their specific use case.
Note that peer relationships are strongest with math and ELA. They also offer relatively good coverage for science (grades 3-12) and some limited coverage for social studies (grades 6-12).
Topics
Where no other relationships yield good results, use Topics to casts a broad net and identify standards covering the same general topic in the desired document. This is a two-step process where you get the list of Topics a standard is related to and then look for standards in the destination state related to one or more of those Topics. Topics cover multiple grades, so you may want to add grade filtering when looking for similar standards.
Topics offer the loosest of the relationships and is good for identifying Standards that editorial staff may want to consider when other relationships don't provide more specific suggestions. Topics are available for the core 4 subject areas.
Resources
Academic Benchmarks has developed example application that can help accelerate the integration of relationships into your system and processes. See the Standards Relationship Browser and Standards Relationship Report generator in our Examples section. They include code samples that can be downloaded from the AB Connect repository and used as a starting point for your implementation.
Limitations
In many instances the Standard in question does not have an exact match in the destination state. Since using relationships does not take the specifics of the content under consideration, your degree of automation is limited. Where there aren't exact matches, editorial staff will need to review system suggestions. With fewer and fewer states adhering to the Common Core, you may find that this isn't the most efficient approach for your team.
Content alignment is not a once and done situation. Standards are constantly evolving. Sometimes Standards within an existing document change. Other times the entire document is replaced by a new version. A one-time mapping using relationships doesn't address the maintenance of alignments over time.
Relationships tend to be strongest and most prevalent with ELA, math and science. Topics have good coverage of social studies.
Peer relationships are limited to authorities in the US.
Crosswalk relationships are currently focused on authorities in the US with limited support in other regions.
Tagging Content and Recommending Relationships
While using relationships to move from one document to another is relatively easy and efficient, at the end of the process you only have one more document's worth of alignments. As you expand your perspective to additional documents, as well as changes over time, you'll need to repeat this process. As you approach alignments across many authorities at one time, however, our robust machine-learning powered recommendation engine that uses your previous decisions to inform predictions can set you up to handle changes over time with a more holistic approach to alignment.
To assist, Academic Benchmarks created a recommendation engine that uses metadata descriptions of content to recommend alignments. In AB Connect, the content is represented by an Asset object and the metadata description is often referred to as an Asset profile.
Using either the API with a user interface in your system or AB Connect's alignment web solution, aligners describe content by tagging it with standards and education search terms. The recommendation engine uses the profile to make recommendations for additional standards.
While this approach takes more upfront effort from aligners to describe the content, it has several distinct advantages:
It works across all authorities and most subjects.
The engine updates recommendations as Standards are changed and new Standards become available easing long term maintenance.
Recommendations are made in the context of the specific content. The process of using relationships ignores the subtlety of the content description and errors can drift into alignments.
How To Offer Your Partners Advanced Discovery Of Your Assets
AB Connect can be a powerful solution for interoperability challenges between systems exchanging content. It is possible to share Assets with other AB Connect customers (referred to as Providers). The Provider who owns the Assets is referred to as the Owner. Providers that can search and read the Asset metadata profile are referred to as Consumers. When access is shared, the Consumer can use AB Connect to include the Owner's Assets in their search results and retrieve the Asset descriptions to power activities like displaying alignment information and finding related content. For example, if you are a Learning Management System (LMS) and have purchased lesson plans from one Provider and assessment questions from another, you can use AB Connect to search the lesson repository, retrieve the description of the plan and look for related questions in the assessment repository (Assets that cover the same Standards and Concepts as the lesson). This capability is facilitated using the Providers resource as well as the Owner property on the Assets. To share your Assets with other Providers, contact AB Support. We can configure the sharing for you.
When using AB Connect for interoperability, you don't need to be concerned about the AB license status of your partners. AB Connect automatically handles the Consumer's licensing and only shares data with them that they have been licensed for. This is true for reading the Asset data as well as searching. E.g. if you are using Concepts in your Asset description, a Consumer that is only licensed for Standards will not be able to include Concepts in their search criteria. Similarly, if you are only licensed for Standards, Consumers of your Assets will not be able to find them using Concepts (or Topics) because your Asset descriptions will not include Concepts (or Topics).
See the owner property in the section on Assets for details on searching by owner.
Exchanging Alignment Data With Partners
A common need in the industry is to exchange alignment and taxonomic metadata with partners to support reporting and discoverability. E.g. a school district purchases lessons from a provider. An administrator at the district imports the lesson into their LMS. While the lesson data is enough to run the lesson, alignment and taxonomies are required in order to support full discovery of the plans and analytics of the lesson usage.
What's the best way to share the content metadata with your partners?
Recommendation: AB Connect's Owner/Consumer Capability
AB Connect allows you (the Owner) to share your content's description (Asset metadata profile) with your partners (Consumers). The Consumers can retrieve your Asset's metadata directly from AB Connect using the AB Asset GUID. This approach has several advantages:
It is concise. One GUID is exchanged with your payload and it conveys the complete Asset metadata profile.
Alignments and other descriptive metadata change over time. New Standards documents are published. Alignments are adjusted. Standards are deleted. Concepts and Topics are added to the description. Exchanging the Asset GUID allows the Consumer to refresh the Asset profile dynamically.
Your AB Connect license is likely not the same as your partner's license. If you send them AB GUIDs that are not in their license, it is a violation of the license agreement and confusing for the recipient since they won't have matching data on their end. If you exchange data using the Asset profile, AB Connect filters the Consumer's view of the Asset to match their license.
Using this approach also enables your partners to search your Assets via AB Connect using the full Asset metadata profile. See the for more information on this advantage.
To setup your account to share your Asset descriptions with your partners, contact AB Support.
Exchanging The Asset GUID Via The Common Cartridge, Thin Common Cartridge, LTI or QTI
The taxonomic classification property in the LOM section of the manifest is a convenient place to pass the AB Asset GUID. As you can see in the example below, the GUID can be exchanged as a taxonomy entry using the source name AcademicBenchmarksAssetGUID.
For example:
Alternative Approach
While using the Asset GUID to exchange metadata with your partners is a better approach, there may be situations where you are limited to passing Standard GUIDs to a partner. The following sections outline how to include AB GUIDs in your payload.
Exchanging AB Standards GUIDs Via Learnosity
Learnosity has integrated directly with AB Connect. This section of their documentation describes their implementation and how to configure Learnosity to work with AB for your content. While you can use custom tags in Learnosity to store your AB GUIDs with any tag name you'd like, to maximize compatibility with Learnosity's integration with AB Connect, we recommend you use the tag name lrn_ab_aligned. Following the Learnosity API documentation on setting tags, the tags portion of the payload might look like:
The Ed-Fi data model supports the tagging of assessment items with AB Standards GUIDs. In the Ed-Fi model, they are referred to as LearningStandards and the AB GUID is stored as the LearningStandardId.
Note that the Ed-Fi ODS will typically only house standards for the given education agency and any related origin standards that they are derived from. You will be unable to add alignments to standards in other states/districts.
Exchanging AB Standards GUIDs Via The Common Cartridge, Thin Common Cartridge, LTI or QTI
IMS Global has a data element to help support the transmission of related Standards data. There does not appear to be a single page on the IMS site that concisely describes the exchange with explanations and examples, so we'll summarize it here.
Recommended Representation
The curriculumStandardsMetadata object has one optional property providerId. Per the IMS Global GUID registry the Academic Benchmarks provider ID is "AB".
The setOfGUIDs object has optional properties region and version. In spite of the inappropriate use of the phrase region, it is our recommendation that providers use the authority description (document.publication.authorities[0].descr) for this field. We'd recommend supplying the document adoption year (document.adopt_year) for the version and create a new setOfGUIDs for each document for which they are supplying Standards.
The setOfGUIDs body consists of repeated labelledGUID objects. That object consists of an optional label element and a required GUID element.
Handling Problems Consuming Alignments From A Partner
In some situations, the consumer of alignment data may have difficulties resolving AB GUIDs they receive in a payload. The difficulties arise from two sources: stale partner caches of AB data and license differences. Both of these issues are addressed when using the API and using the Asset GUID as a means to exchange data. However, if you are exchanging individual Standards GUIDs, here are some tips:
If you receive a GUID that you don't recognize, it is either because it isn't a valid AB GUID, you aren't licensed for that particular GUID (e.g. it may be in a state or subject you haven't licensed), your cache is out of date or your partner's cache is out of date.
If you cache data, try refreshing your cache or call the API to retrieve that specific GUID. If your cache is stale and the GUID is new, the problem should be resolved. One alternative solution is to always use the API directly rather than cache data so you don't have to worry about a stale cache.
If your cache is up to date or you use the API dynamically, your partner may have a stale cache. In that case, the GUID they passed you may no longer be active. If you request the Standard by GUID from the API, even deleted Standards will be returned. You can check the Standard's status to confirm that it has been deleted.
Regardless of whether you cache data or not, if you aren't licensed for a GUID your partner passed to you, you won't be able to access it. However, you can verify this (and determine which additional units you may want to license) by requesting the Standard by GUID from the API. If it is a valid GUID but you aren't licensed for it, the API will respond with a 403. The error payload will include information that will help you work with to add it to your license.
If requesting the Standard by GUID from the API doesn't resolve the issue, the GUID your partner passed is not a valid AB GUID. Contact your partner to help resolve the issue.
Interpreting Courses
In addition to traditional Standards, some authorities provide course definitions that are groups of Standards defined elsewhere but combined separately into a course. Course definitions are captured into publications where the publication_type is set to course. Those are special publications where the top level of Standards represent courses. The Standards that must be covered in the course are available in the course_standards relationship on the Standard. So, for example, to see the Standards that comprise the Florida CPALMS Language Arts - Kindergarten (#5010041) course, you would use the falling call:
The related_courses relationship points in the opposite direction, so you can get a list of courses that a Standard is used in by examining the related_courses relationship. Since related_courses points in the opposite direction of course_standards, an alternative call to the one above that returns the same data would be:
Or you could use a call like the following to get information on all of the courses that reference a standard:
Managing Alignments as Standards Evolve
From time to time, authorities edit their Standards and make minor or major changes. Minor changes are often reflected as change events on Standards but they can also result in the deleting of one Standard and a creation of another. This typically happens when the modification of the Standard is significant enough that it would impact alignments. In this case, the old GUID is retired and a new one to represent the new Standard is created. Major changes come in the form of new documents that replace all of the standards in older documents.
AB Connect offers a couple of solutions to help you manage your alignments as changes occur. One approach is to use AB Connect's prediction algorithms which maintain alignments based on the content description rather than fixed relationships with specific standards. This requires little to no extra work as alignments change. Another approach is to use the Standards relationships available in AB Connect. AB Connect supplies maps from outdated Standards to their replacements. We often refer to these as migration maps. These maps are exposed in the replaces and replaced_by relationships on the Standards. The replaced_by relationship points forward from outdated Standards to their replacements. The replaces relationship points backwards from the new Standards.
If you would like to use the prediction algorithms to maintain alignments, see the section on Managing and Predicting Relationships. If you would prefer to use the migration maps, the first step in the process would be to identify which workflow will work best for your organization. There are two general approaches that can be taken: starting with Standards or starting with Assets.
Starting with Standards
You may want to start with Standards if you have a local cache and use the events endpoint to sync the cache. In this case, you would get notifications for Standards that have been deleted or new documents that are available. You may have a different process for determining which new Standards you need to migrate alignments to or which old Standards you need to update. But whatever the approach, you start with a list of either outdated Standards or new Standards and you need to update alignments to ensure they are current.
If you are starting with a deleted or outdated Standard, the first step is to locate its replacement(s)(their may be more than one replacement). You can use the replaces relationship to search for standards that replace the Standard in question. E.g.
You can combine search criteria if you need to narrow the focus. For example, you can add document GUIDs to look for replacements in the same document when an individual Standard has been deleted.
The example above returns standard A34FE67F-9AEB-4A04-B14C-59BAE6A6404C which is NOT a "same concept" match. In this case, the interpretation of the applicability of the new Standards to the alignment may need to be reviewed by an aligner.
If you are only interested in exact concept matches, you can add that as a criteria. E.g.
But what about when a new document is added? How do you determine which Standards are being outdated? You can reverse the search direction. E.g. You know South Dakota released their 2018 English Language Arts Standards but you are currently aligned to the 2010 Standards. Where do you start? Grab a Standard from the 2018 document and either look at its replaces list or search for Standards in the 2010 document that are replaced by the Standard you are focusing on. We'll do the latter here because it is more interesting.
Here you'll get 00000CD0-D9E7-11E2-BBB0-00249DFF4B22. If you examine the relationship metadata you'll notice that they have the same concepts but not exact same wording.
Once you have the Standard that is being replaced and the Standard that is replacing it, the next step is to identify which Assets will need to be re-aligned. To locate Assets aligned to an outdated Standard (e.g. 0011921D-A923-435C-985F-FBB3C810E735), you can use a call like:
How you update the alignments is dependent on your editorial processes. E.g. can you automatically migrate alignments to new Standards as long as they have the same concepts? Or do you require the same text? What if the text is the same but the Standard moved to a new grade? These are questions that the editorial staff has already answered but they will need to be codified and applied to any automation you build.
Starting with Assets
Now let's flip that over. Rather than tightly monitor Standards, some organizations prefer a periodic review of their content alignments. In this case, you start with the Assets and look for alignments that need to be updated.
It is easy to locate Asset alignments to deleted standards. For a given Asset, you can find alignments to deleted standards using a call like:
Here we only search for Standards that are marked as accepted. There is no need to update rejected alignments and predicted alignments are automatically updated on the next snapshot (POST a set of predictions to the Asset).
Determining what alignments an Asset should have to new documents isn't possible directly from the Asset itself without using the alignment prediction functionality or examining the Standards (or at least documents) involved. So to add alignments to new documents, either use predictions, combine your asset centric approach with the Standards approach mentioned above or start with something like an alignment gap report.
One search you may find helpful is locating all Assets aligned to an older version of a document. So using the example that we used in the Standards centric approach above, the older document is South Dakota's 2010 Language Arts Standards (E1C9B054-DA22-11E2-95B3-3B359DFF4B22). To locate Assets that are good candidates for alignment to the 2018 document, use a call similar to:
Optimizing Use of AB Connect
When working with APIs, it's important to keep performance optimized. There are a few basic practices that can ensure top performance when working with AB Connect.
Faceting
Calculating facets can be time consuming. Custom attributes on Assets can be particularly challenging as they may have unique values which will significantly impact performance. Only facet properties you need and avoid facetting properties that have unique values.
Sparse Fieldsets
Another source of processing and network waste is the processing and returning large quantities of unused fields. We recommend using the fields parameter to request only the specific fields required for each call. Use fields[]=* only for discovery during programming. To ensure the use of wildcards with the fields parameter does not impact overall system performance, such calls are throttled to 2 per second.
Request Only What You Need, Only When You Need It
Using sparse fieldsets and minimizing facet requests are simple changes that can have significant impact on the response times of calls, but the design of the your system's interaction with the API may have a larger impact.
It's tempting to make few calls and pull more data per call because you may need it. While this seems efficient on the surface, it can actually have notable impact on the overall API experience - particularly for user interfaces. In practice, it is typically more efficient and more interactive to make multiple calls and request only enough data to meet the immediate need.
Several examples:
Navigating Standards
One common mistake is to attempt to load a large set of Standards to populate a tree or set of drop-downs. This could take many seconds depending on whether you are loading a section, document or publication. A best practice is to lazy load the UI and request just enough information to show the user what they requested. The AB Connect Standards browser uses this approach for a very efficient interactive experience.
Searching for Assets
Another common scenario is searching for Assets and alignments. It is tempting to show all results or load large pages of Assets but this can result in a slow user experience and users don't typically scroll through large sets of data. It is better to show them a small page of results quickly and allow them to refine their search or page/infinite scroll the results.
Showing Appropriate Amount Of Information
It is tempting to show a lot of data in your search results but not only can this slow API response times but can clutter the user interface making it difficult to digest and navigate. Avoid things like attempting to show large quantities of properties or alignments in Asset search results. It's better to have a list or tiles with a simple title, perhaps a brief description, subject and grade. The user can use faceting to further narrow results and if they need details they drill down into the individual Asset to see things like alignments, concepts, etc.
Know Your Browser
Another common source of waste is retrieving and exposing irrelevant data to your users. If your user is an 8th grade math teacher from California, don't force them to select 8th grade math when searching for content. When displaying alignments, limit your queries to 8th grade math Standards in California. This will significantly reduce the data the system is processing and will speed up the response times.
Retrieve the paginated list of calendar events or assignments for the specified user. To view calendar events for a user other than yourself, you must either be an observer of that user or an administrator.
Request Parameters:
Parameter
Type
Description
type
string
Defaults to “event”
Allowed values: event, assignment
start_date
Date
Only return events since the start_date (inclusive). Defaults to today. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
Context code of the course, group, user, or account to move this event to. Scheduler appointments and events with section-specific times cannot be moved between calendars.
Delete an event from the calendar and return the deleted event
Request Parameters:
Parameter
Type
Description
cancel_reason
string
Reason for deleting/canceling the event.
which
string
Valid if the event whose ID is in the URL is part of a series. Delete just the event whose ID is in in the URL, all events in the series, or the given event and all those following.
Creates and updates “timetable” events for a course. Can automaticaly generate a series of calendar events based on simple schedules (e.g. “Monday and Wednesday at 2:00pm” )
Existing timetable events for the course and course sections will be updated if they still are part of the timetable. Otherwise, they will be deleted.
Request Parameters:
Parameter
Type
Description
timetables[course_section_id][]
Array
An array of timetable objects for the course section specified by course_section_id. If course_section_id is set to “all”, events will be created for the entire course.
timetables[course_section_id][][weekdays]
string
A comma-separated list of abbreviated weekdays (Mon-Monday, Tue-Tuesday, Wed-Wednesday, Thu-Thursday, Fri-Friday, Sat-Saturday, Sun-Sunday)
Creates and updates “timetable” events for a course or course section. Similar to setting a course timetable, but instead of generating a list of events based on a timetable schedule, this endpoint expects a complete list of events.
Request Parameters:
Parameter
Type
Description
course_section_id
string
Events will be created for the course section specified by course_section_id. If not present, events will be created for the entire course.
events[]
Array
An array of event objects to use.
This documentation is generated directly from the Canvas LMS source code, available on Github.
...
{
"data": {
"guid": "9127D390-F1B9-11E5-862E-0938DC287387",
"acronym": null,
"descr": "New York DOE"
},
"count": 20047
},
....
`https://api.abconnect.instructure.com/rest/v4.1/standards?filter[standards]=(document.publication.authorities.guid EQ '9127D390-F1B9-11E5-862E-0938DC287387' AND status EQ 'active')&facet=document.publication&limit=0`
`https://api.abconnect.instructure.com/rest/v4.1/standards?filter[standards]=(document.publication.guid EQ '4D7B5584-9C82-11E7-8A3F-4EABBF03DF2F' AND status EQ 'active')&facet=document&limit=0`
{
// The ID of the calendar event
"id": 234,
// The title of the calendar event
"title": "Paintball Fight!",
// The start timestamp of the event
"start_at": "2012-07-19T15:00:00-06:00",
// The end timestamp of the event
"end_at": "2012-07-19T16:00:00-06:00",
// The HTML description of the event
"description": "<b>It's that time again!</b>",
// The location name of the event
"location_name": "Greendale Community College",
// The address where the event is taking place
"location_address": "Greendale, Colorado",
// the context code of the calendar this event belongs to (course, group, user,
// or account)
"context_code": "course_123",
// if specified, it indicates which calendar this event should be displayed on.
// for example, a section-level event would have the course's context code here,
// while the section's context code would be returned above)
"effective_context_code": null,
// the context name of the calendar this event belongs to (course, user or
// group)
"context_name": "Chemistry 101",
// a comma-separated list of all calendar contexts this event is part of
"all_context_codes": "course_123,course_456",
// Current state of the event ('active', 'locked' or 'deleted') 'locked'
// indicates that start_at/end_at cannot be changed (though the event could be
// deleted). Normally only reservations or time slots with reservations are
// locked (see the Appointment Groups API)
"workflow_state": "active",
// Whether this event should be displayed on the calendar. Only true for
// course-level events with section-level child events.
"hidden": false,
// Normally null. If this is a reservation (see the Appointment Groups API), the
// id will indicate the time slot it is for. If this is a section-level event,
// this will be the course-level parent event.
"parent_event_id": null,
// The number of child_events. See child_events (and parent_event_id)
"child_events_count": 0,
// Included by default, but may be excluded (see include[] option). If this is a
// time slot (see the Appointment Groups API) this will be a list of any
// reservations. If this is a course-level event, this will be a list of
// section-level events (if any)
"child_events": null,
// URL for this calendar event (to update, delete, etc.)
"url": "https://example.com/api/v1/calendar_events/234",
// URL for a user to view this event
"html_url": "https://example.com/calendar?event_id=234&include_contexts=course_123",
// The date of this event
"all_day_date": "2012-07-19",
// Boolean indicating whether this is an all-day event (midnight to midnight)
"all_day": false,
// When the calendar event was created
"created_at": "2012-07-12T10:55:20-06:00",
// When the calendar event was last updated
"updated_at": "2012-07-12T10:55:20-06:00",
// Various Appointment-Group-related fields.These fields are only pertinent to
// time slots (appointments) and reservations of those time slots. See the
// Appointment Groups API. The id of the appointment group
"appointment_group_id": null,
// The API URL of the appointment group
"appointment_group_url": null,
// If the event is a reservation, this a boolean indicating whether it is the
// current user's reservation, or someone else's
"own_reservation": false,
// If the event is a time slot, the API URL for reserving it
"reserve_url": null,
// If the event is a time slot, a boolean indicating whether the user has
// already made a reservation for it
"reserved": false,
// The type of participant to sign up for a slot: 'User' or 'Group'
"participant_type": "User",
// If the event is a time slot, this is the participant limit
"participants_per_appointment": null,
// If the event is a time slot and it has a participant limit, an integer
// indicating how many slots are available
"available_slots": null,
// If the event is a user-level reservation, this will contain the user
// participant JSON (refer to the Users API).
"user": null,
// If the event is a group-level reservation, this will contain the group
// participant JSON (refer to the Groups API).
"group": null,
// Boolean indicating whether this has important dates.
"important_dates": true,
// Identifies the recurring event series this event may belong to.
"series_uuid": null,
// An iCalendar RRULE for defining how events in a recurring event series
// repeat.
"rrule": null,
// Boolean indicating if is the first event in the series of recurring events.
"series_head": null,
// A natural language expression of how events occur in the series.
"series_natural_language": "Daily 5 times",
// Boolean indicating whether this has blackout date.
"blackout_date": true
}
{
// A synthetic ID for the assignment
"id": "assignment_987",
// The title of the assignment
"title": "Essay",
// The due_at timestamp of the assignment
"start_at": "2012-07-19T23:59:00-06:00",
// The due_at timestamp of the assignment
"end_at": "2012-07-19T23:59:00-06:00",
// The HTML description of the assignment
"description": "<b>Write an essay. Whatever you want.</b>",
// the context code of the (course) calendar this assignment belongs to
"context_code": "course_123",
// Current state of the assignment ('published' or 'deleted')
"workflow_state": "published",
// URL for this assignment (note that updating/deleting should be done via the
// Assignments API)
"url": "https://example.com/api/v1/calendar_events/assignment_987",
// URL for a user to view this assignment
"html_url": "http://example.com/courses/123/assignments/987",
// The due date of this assignment
"all_day_date": "2012-07-19",
// Boolean indicating whether this is an all-day event (e.g. assignment due at
// midnight)
"all_day": true,
// When the assignment was created
"created_at": "2012-07-12T10:55:20-06:00",
// When the assignment was last updated
"updated_at": "2012-07-12T10:55:20-06:00",
// The full assignment JSON data (See the Assignments API)
"assignment": null,
// The list of AssignmentOverrides that apply to this event (See the Assignments
// API). This information is useful for determining which students or sections
// this assignment-due event applies to.
"assignment_overrides": null,
// Boolean indicating whether this has important dates.
"important_dates": true,
// An iCalendar RRULE for defining how events in a recurring event series
// repeat.
"rrule": "FREQ=DAILY;INTERVAL=1;COUNT=5",
// Trueif this is the first event in the series of recurring events.
"series_head": null,
// A natural language expression of how events occur in the series.
"series_natural_language": "Daily 5 times"
}
Only return events before the end_date (inclusive). Defaults to start_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. If end_date is the same as start_date, then only events on that day are returned.
undated
boolean
Defaults to false (dated events only). If true, only return undated events and ignore start_date and end_date.
all_events
boolean
Defaults to false (uses start_date, end_date, and undated criteria). If true, all events are returned, ignoring start_date, end_date, and undated criteria.
context_codes[]
string
List of context codes of courses, groups, users, or accounts whose events you want to see. If not specified, defaults to the current user (i.e personal calendar, no course/group events). Limited to 10 context codes, additional ones are ignored. The format of this field is the context type, followed by an underscore, followed by the context id. For example: course_42
excludes[]
Array
Array of attributes to exclude. Possible values are “description”, “child_events” and “assignment”
includes[]
Array
Array of optional attributes to include. Possible values are “web_conference” and “series_natural_language”
important_dates
boolean
Defaults to false. If true, only events with important dates set to true will be returned.
blackout_date
boolean
Defaults to false. If true, only events with blackout date set to true will be returned.
end_date
Date
Only return events before the end_date (inclusive). Defaults to start_date. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ. If end_date is the same as start_date, then only events on that day are returned.
undated
boolean
Defaults to false (dated events only). If true, only return undated events and ignore start_date and end_date.
all_events
boolean
Defaults to false (uses start_date, end_date, and undated criteria). If true, all events are returned, ignoring start_date, end_date, and undated criteria.
context_codes[]
string
List of context codes of courses, groups, users, or accounts whose events you want to see. If not specified, defaults to the current user (i.e personal calendar, no course/group events). Limited to 10 context codes, additional ones are ignored. The format of this field is the context type, followed by an underscore, followed by the context id. For example: course_42
excludes[]
Array
Array of attributes to exclude. Possible values are “description”, “child_events” and “assignment”
submission_types[]
Array
When type is “assignment”, specifies the allowable submission types for returned assignments. Ignored if type is not “assignment” or if exclude_submission_types is provided.
exclude_submission_types[]
Array
When type is “assignment”, specifies the submission types to be excluded from the returned assignments. Ignored if type is not “assignment”.
includes[]
Array
Array of optional attributes to include. Possible values are “web_conference” and “series_natural_language”
important_dates
boolean
Defaults to false If true, only events with important dates set to true will be returned.
blackout_date
boolean
Defaults to false If true, only events with blackout date set to true will be returned.
When true event is considered to span the whole day and times are ignored.
calendar_event[child_event_data][X][start_at]
DateTime
Section-level start time(s) if this is a course event. X can be any identifier, provided that it is consistent across the start_at, end_at and context_code
calendar_event[child_event_data][X][end_at]
DateTime
Section-level end time(s) if this is a course event.
calendar_event[child_event_data][X][context_code]
string
Context code(s) corresponding to the section-level start and end time(s).
calendar_event[duplicate][count]
number
Number of times to copy/duplicate the event. Count cannot exceed 200.
calendar_event[duplicate][interval]
number
Defaults to 1 if duplicate count is set. The interval between the duplicated events.
calendar_event[duplicate][frequency]
string
Defaults to “weekly”. The frequency at which to duplicate the event
Allowed values: daily, weekly, monthly
calendar_event[duplicate][append_iterator]
boolean
Defaults to false. If set to true, an increasing counter number will be appended to the event title when the event is duplicated. (e.g. Event 1, Event 2, Event 3, etc)
calendar_event[rrule]
string
The recurrence rule to create a series of recurring events. Its value is the iCalendar RRULE defining how the event repeats. Unending series not supported.
calendar_event[blackout_date]
boolean
If the blackout_date is true, this event represents a holiday or some other special day that does not count in course pacing.
cancel_existing
boolean
Defaults to false. If true, cancel any previous reservation(s) for this participant and appointment group.
When true event is considered to span the whole day and times are ignored.
calendar_event[child_event_data][X][start_at]
DateTime
Section-level start time(s) if this is a course event. X can be any identifier, provided that it is consistent across the start_at, end_at and context_code
calendar_event[child_event_data][X][end_at]
DateTime
Section-level end time(s) if this is a course event.
calendar_event[child_event_data][X][context_code]
string
Context code(s) corresponding to the section-level start and end time(s).
calendar_event[rrule]
string
Valid if the event whose ID is in the URL is part of a series. This defines the shape of the recurring event series after it’s updated. Its value is the iCalendar RRULE. Unending series are not supported.
which
string
Valid if the event whose ID is in the URL is part of a series. Update just the event whose ID is in in the URL, all events in the series, or the given event and all those following. Some updates may create a new series. For example, changing the start time of this and all following events from the middle of a series.
Allowed values: one, all, following
calendar_event[blackout_date]
boolean
If the blackout_date is true, this event represents a holiday or some other special day that does not count in course pacing.
timetables[course_section_id][][start_time]
string
Time to start each event at (e.g. “9:00 am”)
timetables[course_section_id][][end_time]
string
Time to end each event at (e.g. “9:00 am”)
timetables[course_section_id][][location_name]
string
A location name to set for each event
events[][start_at]
DateTime
Start time for the event
events[][end_at]
DateTime
End time for the event
events[][location_name]
string
Location name for the event
events[][code]
string
A unique identifier that can be used to update the event at a later time If one is not specified, an identifier will be generated based on the start and end times
events[][title]
string
Title for the meeting. If not present, will default to the associated course’s name
Returns the paginated list of conversations for the current user, most recent ones first.
Request Parameters:
Parameter
Type
Description
scope
string
When set, only return conversations of the specified type. For example, set to “unread” to return only conversations that haven’t been read. The default behavior is to return all non-archived conversations (i.e. read and unread).
Allowed values: unread, starred, archived, sent
filter[]
string
When set, only return conversations for the specified courses, groups or users. The id should be prefixed with its type, e.g. “user_123”,
API response field:
id
The unique identifier for the conversation.
subject
The subject of the conversation.
workflow_state
The current state of the conversation (read, unread or archived)
last_message
A <=100 character preview from the most recent message
last_message_at
The timestamp of the latest message
message_count
The number of messages in this conversation
subscribed
Indicates whether the user is actively subscribed to the conversation
private
Indicates whether this is a private conversation (i.e. audience of one)
starred
Whether the conversation is starred
properties
Additional conversation flags (last_author, attachments, media_objects). Each listed property means the flag is set to true (i.e. the current user is the most recent author, there are attachments, or there are media objects)
audience
Array of user ids who are involved in the conversation, ordered by participation level, then alphabetical. Excludes current user, unless this is a monologue.
audience_contexts
Most relevant shared contexts (courses and groups) between current user and other participants. If there is only one participant, it will also include that user’s enrollment(s)/ membership type(s) in each course/group
avatar_url
URL to appropriate icon for this conversation (custom, individual or group avatar, depending on audience)
participants
Array of users (id, name, full_name) participating in the conversation. Includes current user. If ‘include[]=participant_avatars` was passed as an argument, each user in the array will also have an “avatar_url” field. If `include[]=uuid` was passed as an argument, each user in the array will also have an “uuid” field
visible
Boolean, indicates whether the conversation is visible under the current scope and filter. This attribute is always true in the index API response, and is primarily useful in create/update responses so that you can know if the record should be displayed in the UI. The default scope is assumed, unless a scope or filter is passed to the create/update API call.
Create a new conversation with one or more recipients. If there is already an existing private conversation with the given recipients, it will be reused.
Request Parameters:
Parameter
Type
Description
recipients[]
Required string
An array of recipient ids. These may be user ids
subject
string
The subject of the conversation. This is ignored when reusing a conversation. Maximum length is 255 characters.
Returns any currently running conversation batches for the current user. Conversation batches are created when a bulk private message is sent asynchronously (see the mode argument to the create API action).
Returns information for a single conversation for the current user. Response includes all fields that are present in the list/index action as well as messages and extended participant information.
Request Parameters:
Parameter
Type
Description
interleave_submissions
boolean
(Obsolete) Submissions are no longer linked to conversations. This parameter is ignored.
scope
string
Used when generating “visible” in the API response. See the explanation under the
Allowed values: unread, starred, archived
API response field:
participants
Array of relevant users. Includes current user. If there are forwarded messages in this conversation, the authors of those messages will also be included, even if they are not participating in this conversation. Fields include:
messages
Array of messages, newest first. Fields include:
id
The unique identifier for the message
created_at
The timestamp of the message
body
The actual message body
author_id
The id of the user who sent the message (see audience, participants)
generated
If true, indicates this is a system-generated message (e.g. “Bob added Alice to the conversation”)
media_comment
Audio/video comment data for this message (if applicable). Fields include: display_name, content-type, media_id, media_type, url
forwarded_messages
If this message contains forwarded messages, they will be included here (same format as this list). Note that those messages may have forwarded messages of their own, etc.
attachments
Array of attachments for this message. Fields include: display_name, content-type, filename, url
submissions
(Obsolete) Array of assignment submissions having comments relevant to this conversation. Submissions are no longer linked to conversations. This field will always be nil or empty.
Toggle the current user’s subscription to the conversation (only valid for group conversations). If unsubscribed, the user will still have access to the latest messages, but the conversation won’t be automatically flagged as unread, nor will it jump to the top of the inbox.
Add recipients to an existing group conversation. Response is similar to the GET/show action, except that only includes the latest message (e.g. “joe was added to the conversation by bob”)
Request Parameters:
Parameter
Type
Description
recipients[]
Required string
An array of recipient ids. These may be user ids or course/group ids prefixed with “course_” or “group_” respectively, e.g. recipients[]=1&recipients[]=2&recipients[]=course_3
Add a message to an existing conversation. Response is similar to the GET/show action, except that only includes the latest message (i.e. what we just sent)
An array of user ids. Defaults to all of the current conversation recipients. To explicitly send a message to no other recipients, this array should consist of the logged-in user id.
An array of message ids from this conversation to send to recipients of the new message. Recipients who already had a copy of included messages will not be affected.
Request Parameters:
Parameter
Type
Description
body
Required string
The message to be sent.
attachment_ids[]
string
An array of attachments ids. These must be files that have been previously uploaded to the sender’s “conversation attachments” folder.
Delete messages from this conversation. Note that this only affects this user’s view of the conversation. If all messages are deleted, the conversation will be as well (equivalent to DELETE)
{
// the unique identifier for the conversation.
"id": 2,
// the subject of the conversation.
"subject": "2",
// The current state of the conversation (read, unread or archived).
"workflow_state": "unread",
// A <=100 character preview from the most recent message.
"last_message": "sure thing, here's the file",
// the date and time at which the last message was sent.
"start_at": "2011-09-02T12:00:00Z",
// the number of messages in the conversation.
"message_count": 2,
// whether the current user is subscribed to the conversation.
"subscribed": true,
// whether the conversation is private.
"private": true,
// whether the conversation is starred.
"starred": true,
// Additional conversation flags (last_author, attachments, media_objects). Each
// listed property means the flag is set to true (i.e. the current user is the
// most recent author, there are attachments, or there are media objects)
"properties": null,
// Array of user ids who are involved in the conversation, ordered by
// participation level, then alphabetical. Excludes current user, unless this is
// a monologue.
"audience": null,
// Most relevant shared contexts (courses and groups) between current user and
// other participants. If there is only one participant, it will also include
// that user's enrollment(s)/ membership type(s) in each course/group.
"audience_contexts": null,
// URL to appropriate icon for this conversation (custom, individual or group
// avatar, depending on audience).
"avatar_url": "https://canvas.instructure.com/images/messages/avatar-group-50.png",
// Array of users participating in the conversation. Includes current user.
"participants": null,
// indicates whether the conversation is visible under the current scope and
// filter. This attribute is always true in the index API response, and is
// primarily useful in create/update responses so that you can know if the
// record should be displayed in the UI. The default scope is assumed, unless a
// scope or filter is passed to the create/update API call.
"visible": true,
// Name of the course or group in which the conversation is occurring.
"context_name": "Canvas 101"
}
{
// The user ID for the participant.
"id": 2,
// A short name the user has selected, for use in conversations or other less
// formal places through the site.
"name": "Shelly",
// The full name of the user.
"full_name": "Sheldon Cooper",
// If requested, this field will be included and contain a url to retrieve the
// user's avatar.
"avatar_url": "https://canvas.instructure.com/images/messages/avatar-50.png",
// The Canvas UUID for the participant.
"uuid": "W9GQIcdoDTqwX8mxIunDQQVL6WZTaGmpa5xovmCB"
}
"uuid:W9GQIcdoDTqwX8mxIunDQQVL6WZTaGmpa5xovmCB", or "course_456".
For users, you can use either their numeric ID or UUID prefixed with "uuid:".
Can be an array (by setting "filter[]") or single value (by setting "filter")
(either numeric IDs or UUIDs prefixed with "uuid:"),
or course/group ids prefixed with "course_" or "group_" respectively, e.g.
recipients[]=1&recipients[]=uuid:W9GQIcdoDTqwX8mxIunDQQVL6WZTaGmpa5xovmCBx&recipients[]=course_3.
If the course/group has over 100 enrollments, 'bulk_message' and 'group_conversation' must be
set to true.
When filter[] contains multiple filters, combine them with this mode, filtering conversations that at have at least all of the contexts (“and”) or at least one of the contexts (“or”)
Allowed values: and, or, default or
interleave_submissions
boolean
(Obsolete) Submissions are no longer linked to conversations. This parameter is ignored.
include_all_conversation_ids
boolean
Default is false. If true, the top-level element of the response will be an object rather than an array, and will have the keys “conversations” which will contain the paged conversation data, and “conversation_ids” which will contain the ids of all conversations under this scope/filter in the same order.
include[]
string
“participant_avatars”
Optionally include an “avatar_url” key for each user participating in the conversation
“uuid”
Optionally include an “uuid” key for each user participating in the conversation
Allowed values: participant_avatars, uuid
body
Required string
The message to be sent
force_new
boolean
Forces a new message to be created, even if there is an existing private conversation.
group_conversation
boolean
Defaults to false. When false, individual private conversations will be created with each recipient. If true, this will be a group conversation (i.e. all recipients may see all messages and replies). Must be set true if the number of recipients is over the set maximum (default is 100).
attachment_ids[]
string
An array of attachments ids. These must be files that have been previously uploaded to the sender’s “conversation attachments” folder.
media_comment_id
string
Media comment id of an audio or video file to be associated with this message.
media_comment_type
string
Type of the associated media file
Allowed values: audio, video
mode
string
Determines whether the messages will be created/sent synchronously or asynchronously. Defaults to sync, and this option is ignored if this is a group conversation or there is just one recipient (i.e. it must be a bulk private message). When sent async, the response will be an empty array (batch status can be queried via the )
Allowed values: sync, async
scope
string
Used when generating “visible” in the API response. See the explanation under the
Allowed values: unread, starred, archived
filter[]
string
Used when generating “visible” in the API response. See the explanation under the
filter_mode
string
Used when generating “visible” in the API response. See the explanation under the
Allowed values: and, or, default or
context_code
string
The course or group that is the context for this conversation. Same format as courses or groups in the recipients argument.
include[]
string
“uuid”
Optionally include an “uuid” key for each user participating in the conversation
Allowed values: uuid
filter[]
string
Used when generating “visible” in the API response. See the explanation under the
filter_mode
string
Used when generating “visible” in the API response. See the explanation under the
Allowed values: and, or, default or
auto_mark_as_read
boolean
Default true. If true, unread conversations will be automatically marked as read. This will default to false in a future API release, so clients should explicitly send true if that is the desired behavior.
conversation[starred]
boolean
Toggle the starred state of the current user’s view of the conversation.
scope
string
Used when generating “visible” in the API response. See the explanation under the
Allowed values: unread, starred, archived
filter[]
string
Used when generating “visible” in the API response. See the explanation under the
filter_mode
string
Used when generating “visible” in the API response. See the explanation under the
Allowed values: and, or, default or
media_comment_id
string
Media comment id of an audio of video file to be associated with this message.
A paginated list of accounts that the current user can view or manage. Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in.
Request Parameters:
Parameter
Type
Description
Returns a list of objects.
GET /api/v1/horizon_accounts
Scope:url:GET|/api/v1/horizon_accounts
A paginated list of horizon accounts that the current user can view or manage. Returns all accounts with the horizon_account setting enabled. If there are any horizon accounts and the user has access to Site Admin, Site Admin will also be included in the results.
Typically, students and even teachers will get an empty list in response, only account admins can view the accounts that they are in.
Request Parameters:
Parameter
Type
Description
Returns a list of objects.
GET /api/v1/manageable_accounts
Scope:url:GET|/api/v1/manageable_accounts
A paginated list of accounts where the current user has permission to create or manage courses. List will be empty for students and teachers as only admins can view which accounts they are in.
Returns a list of objects.
GET /api/v1/course_creation_accounts
Scope:url:GET|/api/v1/course_creation_accounts
A paginated list of accounts where the current user has permission to create courses.
Returns a list of objects.
GET /api/v1/course_accounts
Scope:url:GET|/api/v1/course_accounts
A paginated list of accounts that the current user can view through their admin course enrollments. (Teacher, TA, or designer enrollments). Only returns “id”, “name”, “workflow_state”, “root_account_id” and “parent_account_id”
Returns a list of objects.
GET /api/v1/accounts/:id
Scope:url:GET|/api/v1/accounts/:id
Retrieve information on an individual account, given by id or sis sis_account_id.
Returns a JSON object containing a subset of settings for the specified account. It’s possible an empty set will be returned if no settings are applicable. The caller must be an Account admin with the manage_account_settings permission.
Example Request:
Example Response:
GET /api/v1/settings/environment
Scope:url:GET|/api/v1/settings/environment
Return a hash of global settings for the root account This is the same information supplied to the web interface as ENV.SETTINGS.
Returns permission information for the calling user and the given account. You may use self as the account id to check permissions against the domain root account. The caller must have an account role or admin (teacher/TA/designer) enrollment in a course in the account.
Delete a user record from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts.
WARNING: This API will allow a user to remove themselves from the account. If they do this, they won’t be able to make API calls or log into Canvas at that account.
Delete multiple users from a Canvas root account. If a user is associated with multiple root accounts (in a multi-tenant instance of Canvas), this action will NOT remove them from the other accounts.
WARNING: This API will allow a user to remove themselves from the account. If they do this, they won’t be able to make API calls or log into Canvas at that account.
Example Request:
Returns a object.
PUT /api/v1/accounts/:account_id/users/bulk_update
If true, include only published courses. If false, exclude published courses. If not present, do not filter on published status.
completed
boolean
If true, include only completed courses (these may be in state ‘completed’, or their enrollment term may have ended). If false, exclude completed courses. If not present, do not filter on completed status.
blueprint
boolean
If true, include only blueprint courses. If false, exclude them. If not present, do not filter on this basis.
blueprint_associated
boolean
If true, include only courses that inherit content from a blueprint course. If false, exclude them. If not present, do not filter on this basis.
public
boolean
If true, include only public courses. If false, exclude them. If not present, do not filter on this basis.
by_teachers[]
integer
List of User IDs of teachers; if supplied, include only courses taught by one of the referenced users.
by_subaccounts[]
integer
List of Account IDs; if supplied, include only courses associated with one of the referenced subaccounts.
hide_enrollmentless_courses
boolean
If present, only return courses that have at least one enrollment. Equivalent to ‘with_enrollments=true’; retained for compatibility.
state[]
string
If set, only return courses that are in the given state(s). By default, all states but “deleted” are returned.
Allowed values: created, claimed, available, completed, deleted, all
enrollment_term_id
integer
If set, only includes courses from the specified term.
search_term
string
The partial course name, code, or full ID to match and return in the results list. Must be at least 3 characters.
include[]
string
All explanations can be seen in the
“sections”, “needs_grading_count” and “total_scores” are not valid options at the account level
The filter to search by. “course” searches for course names, course codes, and SIS IDs. “teacher” searches for teacher names
Allowed values: course, teacher
starts_before
Date
If set, only return courses that start before the value (inclusive) or their enrollment term starts before the value (inclusive) or both the course’s start_at and the enrollment term’s start_at are set to null. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
ends_after
Date
If set, only return courses that end after the value (inclusive) or their enrollment term ends after the value (inclusive) or both the course’s end_at and the enrollment term’s end_at are set to null. The value should be formatted as: yyyy-mm-dd or ISO 8601 YYYY-MM-DDTHH:MM:SSZ.
homeroom
boolean
If set, only return homeroom courses.
string
The default time zone of the account. Allowed time zones are or friendlier .
account[default_storage_quota_mb]
integer
The default course storage quota to be used, if not otherwise specified.
account[default_user_storage_quota_mb]
integer
The default user storage quota to be used, if not otherwise specified.
account[default_group_storage_quota_mb]
integer
The default group storage quota to be used, if not otherwise specified.
account[course_template_id]
integer
The ID of a course to be used as a template for all newly created courses. Empty means to inherit the setting from parent account, 0 means to not use a template even if a parent account has one set. The course must be marked as a template.
account[parent_account_id]
integer
The ID of a parent account to move the account to. The new parent account must be in the same root account as the original. The hierarchy of sub-accounts will be preserved in the new parent account. The caller must be an administrator in both the original parent account and the new parent account.
Restrict students from viewing courses before start date
account[settings][microsoft_sync_enabled]
boolean
Determines whether this account has Microsoft Teams Sync enabled or not.
Note that if you are altering Microsoft Teams sync settings you must enable the Microsoft Group enrollment syncing feature flag. In addition, if you are enabling Microsoft Teams sync, you must also specify a tenant, login attribute, and a remote attribute. Specifying a suffix to use is optional.
account[settings][microsoft_sync_tenant]
string
The tenant this account should use when using Microsoft Teams Sync. This should be an Azure Active Directory domain name.
account[settings][microsoft_sync_login_attribute]
string
The attribute this account should use to lookup users when using Microsoft Teams Sync. Must be one of “sub”, “email”, “oid”, “preferred_username”, or “integration_id”.
A suffix that will be appended to the result of the login attribute when associating Canvas users with Microsoft users. Must be under 255 characters and contain no whitespace. This field is optional.
The Active Directory attribute to use when associating Canvas users with Microsoft users. Must be one of “mail”, “mailNickname”, or “userPrincipalName”.
Enable or disable individual learning paths for students based on assessment
account[settings][conditional_release][locked]
boolean
Lock this setting for sub-accounts and courses
account[settings][enable_course_paces][value]
boolean
Enable or disable course pacing
account[settings][enable_course_paces][locked]
boolean
Lock this setting for sub-accounts and courses
account[settings][password_policy]
Hash
Hash of optional password policy configuration parameters for a root account
allow_login_suspension boolean
Allow suspension of user logins upon reaching maximum_login_attempts
require_number_characters boolean
Require the use of number characters when setting up a new password
account[settings][enable_as_k5_account][value]
boolean
Enable or disable Canvas for Elementary for this account
account[settings][use_classic_font_in_k5][value]
boolean
Whether or not the classic font is used on the dashboard. Only applies if enable_as_k5_account is true.
account[settings][horizon_account][value]
boolean
Enable or disable Canvas Career for this account
override_sis_stickiness
boolean
Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness
List of permissions to check against the authenticated user. Permission names are documented in the List assignable permissions endpoint.
recursive
boolean
If true, the entire account tree underneath this account will be returned (though still paginated). If false, only direct sub-accounts of this account will be returned. Defaults to false.
order
string
Sorts the accounts by id or name. Only applies when recursive is false. Defaults to id.
Allowed values: id, name
with_enrollments
boolean
If true, include only courses with at least one enrollment. If false, include only courses with no enrollments. If not present, do not filter on course enrollment status.
enrollment_type[]
string
If set, only return courses that have at least one user enrolled in in the course with one of the specified enrollment types.
Allowed values: teacher, student, ta, observer, designer
account[name]
string
Updates the account name
account[sis_account_id]
string
Updates the account sis_account_id Must have manage_sis permission and must not be a root_account.
user_ids
string
Array
The IDs of the users to update.
user
Hash
The attributes to update for each user.
account[name]
Required string
The name of the new sub-account.
account[sis_account_id]
string
The account’s identifier in the Student Information System.
{
// the ID of the Account object
"id": 2,
// The display name of the account
"name": "Canvas Account",
// The UUID of the account
"uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5",
// The account's parent ID, or null if this is the root account
"parent_account_id": 1,
// The ID of the root account, or null if this is the root account
"root_account_id": 1,
// The storage quota for the account in megabytes, if not otherwise specified
"default_storage_quota_mb": 500,
// The storage quota for a user in the account in megabytes, if not otherwise
// specified
"default_user_storage_quota_mb": 50,
// The storage quota for a group in the account in megabytes, if not otherwise
// specified
"default_group_storage_quota_mb": 50,
// The default time zone of the account. Allowed time zones are
// {http://www.iana.org/time-zones IANA time zones} or friendlier
// {http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html Ruby on Rails
// time zones}.
"default_time_zone": "America/Denver",
// The account's identifier in the Student Information System. Only included if
// the user has permission to view SIS information.
"sis_account_id": "123xyz",
// The account's identifier in the Student Information System. Only included if
// the user has permission to view SIS information.
"integration_id": "123xyz",
// The id of the SIS import if created through SIS. Only included if the user
// has permission to manage SIS information.
"sis_import_id": 12,
// The number of courses directly under the account (available via include)
"course_count": 10,
// The number of sub-accounts directly under the account (available via include)
"sub_account_count": 10,
// The account's identifier that is sent as context_id in LTI launches.
"lti_guid": "123xyz",
// The state of the account. Can be 'active' or 'deleted'.
"workflow_state": "active"
}
{
// Terms Of Service id
"id": 1,
// The given type for the Terms of Service
"terms_type": "default",
// Boolean dictating if the user must accept Terms of Service
"passive": false,
// The id of the root account that owns the Terms of Service
"account_id": 1,
// Content of the Terms of Service
"content": "To be or not to be that is the question",
// The type of self registration allowed
"self_registration_type": "["none", "observer", "all"]"
}
{
// The ID of the help link
"id": "instructor_question",
// The name of the help link
"text": "Ask Your Instructor a Question",
// The description of the help link
"subtext": "Questions are submitted to your instructor",
// The URL of the help link
"url": "#teacher_feedback",
// The type of the help link
"type": "default",
// The roles that have access to this help link
"available_to": ["user", "student", "teacher", "admin", "observer", "unenrolled"]
}
{
// Help link button title
"help_link_name": "Help And Policies",
// Help link button icon
"help_link_icon": "help",
// Help links defined by the account. Could include default help links.
"custom_help_links": [{"id":"link1","text":"Custom Link!","subtext":"Something something.","url":"https:\/\/google.com","type":"custom","available_to":["user","student","teacher","admin","observer","unenrolled"],"is_featured":true,"is_new":false,"feature_headline":"Check this out!"}],
// Default help links provided when account has not set help links of their own.
"default_help_links": [{"available_to":["student"],"text":"Ask Your Instructor a Question","subtext":"Questions are submitted to your instructor","url":"#teacher_feedback","type":"default","id":"instructor_question","is_featured":false,"is_new":true,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Search the Canvas Guides","subtext":"Find answers to common questions","url":"https:\/\/community.canvaslms.com\/t5\/Guides\/ct-p\/guides","type":"default","id":"search_the_canvas_guides","is_featured":false,"is_new":false,"feature_headline":""}, {"available_to":["user","student","teacher","admin","observer","unenrolled"],"text":"Report a Problem","subtext":"If Canvas misbehaves, tell us about it","url":"#create_ticket","type":"default","id":"report_a_problem","is_featured":false,"is_new":false,"feature_headline":""}]
}
The entry must have been created by the current user, or the current user must have admin rights to the discussion. If the edit is not allowed, a 401 will be returned.
The entry must have been created by the current user, or the current user must have admin rights to the discussion. If the delete is not allowed, a 401 will be returned.
The discussion will be marked deleted, and the user_id and message will be cleared out.
Example Request:
GET /api/v1/courses/:course_id/discussion_topics/:topic_id
Returns: (1) last userInput (what current user had keyed in to produce the last discussion summary), (2) last discussion summary generated by the current user for current discussion topic, based on userInput, (3) and some usage information.
Example Request:
Example Response:
POST /api/v1/courses/:course_id/discussion_topics/:topic_id/summaries
Return a cached structure of the discussion topic, containing all entries, their authors, and their message bodies.
May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.
In some rare situations, this cached structure may not be available yet. In that case, the server will respond with a 503 error, and the caller should try again soon.
The response is an object containing the following keys:
“participants”: A list of summary information on users who have posted to the discussion. Each value is an object containing their id, display_name, and avatar_url.
“unread_entries”: A list of entry ids that are unread by the current user. this implies that any entry not in this list is read.
“entry_ratings”: A map of entry ids to ratings by the current user. Entries not in this list have no rating. Only populated if rating is enabled.
Example Request:
Example Response:
POST /api/v1/courses/:course_id/discussion_topics/:topic_id/entries
Retrieve the (paginated) top-level entries in a discussion topic.
May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.
Will include the 10 most recent replies, if any, for each entry returned.
If the topic is a root topic with children corresponding to groups of a group assignment, entries from those subtopics for which the user belongs to the corresponding group will be returned.
Ordering of returned entries is newest-first by posting timestamp (reply activity is ignored).
API response field:
id
The unique identifier for the entry.
user_id
The unique identifier for the author of the entry.
editor_id
The unique user id of the person to last edit the entry, if different than user_id.
user_name
The name of the author of the entry.
message
The content of the entry.
read_state
The read state of the entry, “read” or “unread”.
forced_read_state
Whether the read_state was forced (was set manually)
created_at
The creation time of the entry, in ISO8601 format.
updated_at
The updated time of the entry, in ISO8601 format.
attachment
JSON representation of the attachment for the entry, if any. Present only if there is an attachment.
attachments
Deprecated. Same as attachment, but returned as a one-element array. Present only if there is an attachment.
recent_replies
The 10 most recent replies for the entry, newest first. Present only if there is at least one reply.
has_more_replies
True if there are more than 10 replies for the entry (i.e., not all were included in this response). Present only if there is at least one reply.
Example Response:
POST /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies
Add a reply to an entry in a discussion topic. Returns a json representation of the created reply (see documentation for ‘replies’ method) on success.
May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.
Request Parameters:
Parameter
Type
Description
Example Request:
GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entries/:entry_id/replies
Retrieve the (paginated) replies to a top-level entry in a discussion topic.
May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.
Ordering of returned entries is newest-first by creation timestamp.
API response field:
id
The unique identifier for the reply.
user_id
The unique identifier for the author of the reply.
editor_id
The unique user id of the person to last edit the entry, if different than user_id.
user_name
The name of the author of the reply.
message
The content of the reply.
read_state
The read state of the entry, “read” or “unread”.
forced_read_state
Whether the read_state was forced (was set manually)
created_at
The creation time of the reply, in ISO8601 format.
Example Response:
GET /api/v1/courses/:course_id/discussion_topics/:topic_id/entry_list
Retrieve a paginated list of discussion entries, given a list of ids.
May require (depending on the topic) that the user has posted in the topic. If it is required, and the user has not posted, will respond with a 403 Forbidden status and the body ‘require_initial_post’.
Request Parameters:
Parameter
Type
Description
API response field:
id
The unique identifier for the reply.
user_id
The unique identifier for the author of the reply.
user_name
The author’s display name, or null for anonymous topics when the author is not an instructor.
message
The content of the reply.
read_state
The read state of the entry, “read” or “unread”.
forced_read_state
Whether the read_state was forced (was set manually)
created_at
The creation time of the reply, in ISO8601 format.
deleted
If the entry has been deleted, returns true. The user_id, user_name, and message will not be returned for deleted entries.
Example Request:
Example Response:
PUT /api/v1/courses/:course_id/discussion_topics/:topic_id/read
Unsubscribe from a topic to stop receiving notifications about new entries
On success, the response will be 204 No Content with an empty body
Example Request:
This documentation is generated directly from the Canvas LMS source code, available .
string
Only return discussion topics in the given state(s). Defaults to including all topics. Filtering is done after pagination, so pages may be smaller than requested if topics are filtered. Can pass multiple states as comma separated string.
Return announcements instead of discussion topics. Defaults to false
filter_by
string
The state of the discussion topic to return. Currently only supports unread state.
Allowed values: all, unread
search_term
string
The partial title of the discussion topics to match and return.
exclude_context_module_locked_topics
boolean
For students, exclude topics that are locked by module progression. Defaults to false.
string
The type of discussion. Defaults to side_comment or not_threaded if not value is given. Accepted values are ‘side_comment’, ‘not_threaded’ for discussions that only allow one level of nested comments, and ‘threaded’ for fully threaded discussions.
Whether this topic is published (true) or draft state (false). Only teachers and TAs have the ability to create draft state topics.
delayed_post_at
DateTime
If a timestamp is given, the topic will not be published until that time.
allow_rating
boolean
Whether or not users can rate entries in this topic.
lock_at
DateTime
If a timestamp is given, the topic will be scheduled to lock at the provided timestamp. If the timestamp is in the past, the topic will be locked.
podcast_enabled
boolean
If true, the topic will have an associated podcast feed.
podcast_has_student_posts
boolean
If true, the podcast will include posts from students as well. Implies podcast_enabled.
require_initial_post
boolean
If true then a user may not respond to other replies until that user has made an initial reply. Defaults to false.
assignment
Assignment
To create an assignment discussion, pass the assignment parameters as a sub-object. See the for the available parameters. The name parameter will be ignored, as it’s taken from the discussion title. If you want to make a discussion that was an assignment NOT an assignment, pass set_assignment = false as part of the assignment object
is_announcement
boolean
If true, this topic is an announcement. It will appear in the announcement’s section rather than the discussions section. This requires announcment-posting permissions.
pinned
boolean
If true, this topic will be listed in the “Pinned Discussion” section
position_after
string
By default, discussions are sorted chronologically by creation date, you can pass the id of another topic to have this one show up after the other when they are listed.
group_category_id
integer
If present, the topic will become a group discussion assigned to the group.
only_graders_can_rate
boolean
If true, only graders will be allowed to rate entries.
sort_order
string
Default sort order of the discussion. Accepted values are “asc”, “desc”.
Allowed values: asc, desc
sort_order_locked
boolean
If true, users cannot choose their prefered sort order
expanded
boolean
If true, thread will be expanded by default
expanded_locked
boolean
If true, users cannot choose their prefered thread expansion setting
sort_by_rating
boolean
(DEPRECATED) If true, entries will be sorted by rating.
attachment
File
A multipart/form-data form-field-style attachment. Attachments larger than 1 kilobyte are subject to quota restrictions.
specific_sections
string
A comma-separated list of sections ids to which the discussion topic should be made specific to. If it is not desired to make the discussion topic specific to sections, then this parameter may be omitted or set to “all”. Can only be present only on announcements and only those that are for a course (as opposed to a group).
lock_comment
boolean
If is_announcement and lock_comment are true, ‘Allow Participants to Comment’ setting is disabled.
string
The type of discussion. Defaults to side_comment or not_threaded if not value is given. Accepted values are ‘side_comment’, ‘not_threaded’ for discussions that only allow one level of nested comments, and ‘threaded’ for fully threaded discussions.
Whether this topic is published (true) or draft state (false). Only teachers and TAs have the ability to create draft state topics.
delayed_post_at
DateTime
If a timestamp is given, the topic will not be published until that time.
lock_at
DateTime
If a timestamp is given, the topic will be scheduled to lock at the provided timestamp. If the timestamp is in the past, the topic will be locked.
podcast_enabled
boolean
If true, the topic will have an associated podcast feed.
podcast_has_student_posts
boolean
If true, the podcast will include posts from students as well. Implies podcast_enabled.
require_initial_post
boolean
If true then a user may not respond to other replies until that user has made an initial reply. Defaults to false.
assignment
Assignment
To create an assignment discussion, pass the assignment parameters as a sub-object. See the for the available parameters. The name parameter will be ignored, as it’s taken from the discussion title. If you want to make a discussion that was an assignment NOT an assignment, pass set_assignment = false as part of the assignment object
is_announcement
boolean
If true, this topic is an announcement. It will appear in the announcement’s section rather than the discussions section. This requires announcment-posting permissions.
pinned
boolean
If true, this topic will be listed in the “Pinned Discussion” section
position_after
string
By default, discussions are sorted chronologically by creation date, you can pass the id of another topic to have this one show up after the other when they are listed.
group_category_id
integer
If present, the topic will become a group discussion assigned to the group.
allow_rating
boolean
If true, users will be allowed to rate entries.
only_graders_can_rate
boolean
If true, only graders will be allowed to rate entries.
sort_order
string
Default sort order of the discussion. Accepted values are “asc”, “desc”.
Allowed values: asc, desc
sort_order_locked
boolean
If true, users cannot choose their prefered sort order
expanded
boolean
If true, thread will be expanded by default
expanded_locked
boolean
If true, users cannot choose their prefered thread expansion setting
sort_by_rating
boolean
(DEPRECATED) If true, entries will be sorted by rating.
specific_sections
string
A comma-separated list of sections ids to which the discussion topic should be made specific too. If it is not desired to make the discussion topic specific to sections, then this parameter may be omitted or set to “all”. Can only be present only on announcements and only those that are for a course (as opposed to a group).
lock_comment
boolean
If is_announcement and lock_comment are true, ‘Allow Participants to Comment’ setting is disabled.
“forced_entries”: A list of entry ids that have forced_read_state set to true. This flag is meant to indicate the entry’s read_state has been manually set to ‘unread’ by the user, so the entry should not be automatically marked as read.
“view”: A threaded view of all the entries in the discussion, containing the id, user_id, and message.
“new_entries”: Because this view is eventually consistent, it’s possible that newly created or updated entries won’t yet be reflected in the view. If the application wants to also get a flat list of all entries not yet reflected in the view, pass include_new_entries=1 to the request and this array of entries will be returned. These entries are returned in a flat array, in ascending created_at order.
include[]
string
If “all_dates” is passed, all dates associated with graded discussions’ assignments will be included. if “sections” is passed, includes the course sections that are associated with the topic, if the topic is specific to certain sections of the course. If “sections_user_count” is passed, then:
If “overrides” is passed, the overrides for the assignment will be included
Determines the order of the discussion topic list. Defaults to “position”.
Allowed values: position, recent_activity, title
title
string
no description
message
string
no description
title
string
no description
message
string
no description
order[]
Required integer
The ids of the pinned discussion topics in the desired order. (For example, “order=104,102,103”.)
message
string
The updated body of the entry.
include[]
string
If “all_dates” is passed, all dates associated with graded discussions’ assignments will be included. if “sections” is passed, includes the course sections that are associated with the topic, if the topic is specific to certain sections of the course. If “sections_user_count” is passed, then:
If “overrides” is passed, the overrides for the assignment will be included
// A discussion topic
{
// The ID of this topic.
"id": 1,
// The topic title.
"title": "Topic 1",
// The HTML content of the message body.
"message": "<p>content here</p>",
// The URL to the discussion topic in canvas.
"html_url": "https://<canvas>/courses/1/discussion_topics/2",
// The datetime the topic was posted. If it is null it hasn't been posted yet.
// (see delayed_post_at)
"posted_at": "2037-07-21T13:29:31Z",
// The datetime for when the last reply was in the topic.
"last_reply_at": "2037-07-28T19:38:31Z",
// If true then a user may not respond to other replies until that user has made
// an initial reply. Defaults to false.
"require_initial_post": false,
// Whether or not posts in this topic are visible to the user.
"user_can_see_posts": true,
// The count of entries in the topic.
"discussion_subentry_count": 0,
// The read_state of the topic for the current user, 'read' or 'unread'.
"read_state": "read",
// The count of unread entries of this topic for the current user.
"unread_count": 0,
// Whether or not the current user is subscribed to this topic.
"subscribed": true,
// (Optional) Why the user cannot subscribe to this topic. Only one reason will
// be returned even if multiple apply. Can be one of: 'initial_post_required':
// The user must post a reply first; 'not_in_group_set': The user is not in the
// group set for this graded group discussion; 'not_in_group': The user is not
// in this topic's group; 'topic_is_announcement': This topic is an announcement
"subscription_hold": "not_in_group_set",
// The unique identifier of the assignment if the topic is for grading,
// otherwise null.
"assignment_id": null,
// The datetime to publish the topic (if not right away).
"delayed_post_at": null,
// Whether this discussion topic is published (true) or draft state (false)
"published": true,
// The datetime to lock the topic (if ever).
"lock_at": null,
// Whether or not the discussion is 'closed for comments'.
"locked": false,
// Whether or not the discussion has been 'pinned' by an instructor
"pinned": false,
// Whether or not this is locked for the user.
"locked_for_user": true,
// (Optional) Information for the user about the lock. Present when
// locked_for_user is true.
"lock_info": null,
// (Optional) An explanation of why this is locked for the user. Present when
// locked_for_user is true.
"lock_explanation": "This discussion is locked until September 1 at 12:00am",
// The username of the topic creator.
"user_name": "User Name",
// DEPRECATED An array of topic_ids for the group discussions the user is a part
// of.
"topic_children": [5, 7, 10],
// An array of group discussions the user is a part of. Fields include: id,
// group_id
"group_topic_children": [{"id":5,"group_id":1}, {"id":7,"group_id":5}, {"id":10,"group_id":4}],
// If the topic is for grading and a group assignment this will point to the
// original topic in the course.
"root_topic_id": null,
// If the topic is a podcast topic this is the feed url for the current user.
"podcast_url": "/feeds/topics/1/enrollment_1XAcepje4u228rt4mi7Z1oFbRpn3RAkTzuXIGOPe.rss",
// The type of discussion. Values are 'side_comment' or 'not_threaded', for
// discussions that only allow one level of nested comments, and 'threaded' for
// fully threaded discussions.
"discussion_type": "side_comment",
// The unique identifier of the group category if the topic is a group
// discussion, otherwise null.
"group_category_id": null,
// Array of file attachments.
"attachments": null,
// The current user's permissions on this topic.
"permissions": {"attach":true},
// Whether or not users can rate entries in this topic.
"allow_rating": true,
// Whether or not grade permissions are required to rate entries.
"only_graders_can_rate": true,
// DEPRECATED, Whether or not entries should be sorted by rating.
"sort_by_rating": true,
// How entries should be sorted by default.
"sort_order": "asc",
// Can users decide their preferred sort order.
"sort_order_locked": true,
// Threaded replies should be expanded by default.
"expand": true,
// Can users decide their preferred thread expand setting.
"expand_locked": true
}
(a) If sections were asked for and the topic is specific to certain
course sections, includes the number of users in each
section. (as part of the section json asked for above)
(b) Else, includes at the root level the total number of users in the
topic's context (group or course) that the topic applies to.
(a) If sections were asked for and the topic is specific to certain
course sections, includes the number of users in each
section. (as part of the section json asked for above)
(b) Else, includes at the root level the total number of users in the
topic's context (group or course) that the topic applies to.
{
"id": 1,
"userInput": "Give me a brief summary of the discussion.",
"text": "This is a summary of the discussion topic.",
"usage": { "currentCount": 1, "limit": 5 }
}
curl https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/summaries \
-X POST \
-H 'Authorization: Bearer <token>'
{
"id": 1,
"text": "This is a summary of the discussion topic.",
"usage": { "currentCount": 1, "limit": 5 }
}
curl -X PUT https://<canvas>/api/v1/courses/<course_id>/discussion_topics/<topic_id>/disable_summary \
Update due dates and availability dates for multiple assignments in a course.
Accepts a JSON array of objects containing two keys each: id, the assignment id, and all_dates, an array of AssignmentDate structures containing the base and/or override dates for the assignment, as returned from the endpoint with include[]=all_dates.
This endpoint cannot create or destroy assignment overrides; any existing assignment overrides that are not referenced in the arguments will be left alone. If an override is given, any dates that are not supplied with it will be defaulted. To clear a date, specify null explicitly.
All referenced assignments will be validated before any are saved. A list of errors will be returned if any provided dates are invalid, and no changes will be saved.
The bulk update is performed in a background job, use the to check its status.
Example Request:
Returns a object.
GET /api/v1/courses/:course_id/assignments/:assignment_id/check_allocation_conversion
One of student_ids, group_id, or course_section_id must be present. At most one should be present; if multiple are present only the most specific (student_ids first, then group_id, then course_section_id) is used and any others are ignored.
Request Parameters:
Parameter
Type
Description
Example Request:
Returns an object.
PUT /api/v1/courses/:course_id/assignments/:assignment_id/overrides/:id
All current overridden values must be supplied if they are to be retained; e.g. if due_at was overridden, but this PUT omits a value for due_at, due_at will no longer be overridden. If the override is adhoc and student_ids is not supplied, the target override set is unchanged. Target override sets cannot be changed for group or section overrides.
Returns a list of specified overrides in this course, providing they target sections/groups/students visible to the current user. Returns null elements in the list for requests that were not found.
Request Parameters:
Parameter
Type
Description
Example Request:
Returns a list of objects.
POST /api/v1/courses/:course_id/assignments/overrides
Creates the specified overrides for each assignment. Handles creation in a transaction, so all records are created or none are.
One of student_ids, group_id, or course_section_id must be present. At most one should be present; if multiple are present only the most specific (student_ids first, then group_id, then course_section_id) is used and any others are ignored.
Errors are reported in an errors attribute, an array of errors corresponding to inputs. Global errors will be reported as a single element errors array
Request Parameters:
Parameter
Type
Description
Example Request:
Returns a list of objects.
PUT /api/v1/courses/:course_id/assignments/overrides
Updates a list of specified overrides for each assignment. Handles overrides in a transaction, so either all updates are applied or none. See for available attributes.
All current overridden values must be supplied if they are to be retained; e.g. if due_at was overridden, but this PUT omits a value for due_at, due_at will no longer be overridden. If the override is adhoc and student_ids is not supplied, the target override set is unchanged. Target override sets cannot be changed for group or section overrides.
Errors are reported in an errors attribute, an array of errors corresponding to inputs. Global errors will be reported as a single element errors array
Request Parameters:
Parameter
Type
Description
Example Request:
Returns a list of objects.
Appendixes
Appendix: Group assignments
The following diagram provides an example to describe the structure of group assignments. It also shows the correspondence between the fields of an assignment override API request and the resources they map to.
The components in yellow are group sets. When creating or updating an assignment override, you will refer to the group set by the group_category_id field.
The components in green are groups. An assignment can become a group assignment iff it has a group_category_id that maps to an active group set, as well as a group_id that maps to an active, valid group. In the API, you will be specifying the group by the group_id field of the assignment_override construct.
Important: an assignment must be assigned to a group set (the group_category_id field) on creation for an override with a group_id to be effective.
See Also:
This documentation is generated directly from the Canvas LMS source code, available .
boolean
Apply assignment overrides for each assignment, defaults to true.
needs_grading_count_by_section
boolean
Split up “needs_grading_count” by sections into the “needs_grading_count_by_section” key, defaults to false
bucket
string
If included, only return certain assignments depending on due date and submission status.
Determines the order of the assignments. Defaults to “position”.
Allowed values: position, name, due_at
post_to_sis
boolean
Return only assignments that have post_to_sis set or not set.
new_quizzes
boolean
Return only New Quizzes assignments
boolean
Split up “needs_grading_count” by sections into the “needs_grading_count_by_section” key, defaults to false
all_dates
boolean
All dates associated with the assignment, if applicable
string
List of supported submission types for the assignment. Unless the assignment is allowing online submissions, the array should only have one element.
If not allowing online submissions, your options are:
If you are allowing online submissions, you can have one or many allowed submission types:
Allowed values: online_quiz, none
assignment[allowed_extensions][]
string
Allowed extensions if submission_types includes “online_upload”
Example:
assignment[turnitin_enabled]
boolean
Only applies when the Turnitin plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles Turnitin submissions for the assignment. Will be ignored if Turnitin is not available for the course.
assignment[vericite_enabled]
boolean
Only applies when the VeriCite plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles VeriCite submissions for the assignment. Will be ignored if VeriCite is not available for the course.
assignment[turnitin_settings]
string
Settings to send along to turnitin. See Assignment object definition for format.
assignment[integration_data]
string
Data used for SIS integrations. Requires admin-level token with the “Manage SIS” permission. JSON string required.
assignment[integration_id]
string
Unique ID from third party integrations
assignment[peer_reviews]
boolean
If submission_types does not include external_tool,discussion_topic, online_quiz, or on_paper, determines whether or not peer reviews will be turned on for the assignment.
assignment[automatic_peer_reviews]
boolean
Whether peer reviews will be assigned automatically by Canvas or if teachers must manually assign peer reviews. Does not apply if peer reviews are not enabled.
assignment[notify_of_update]
boolean
If true, Canvas will send a notification to students in the class notifying them that the content has changed.
assignment[group_category_id]
integer
If present, the assignment will become a group assignment assigned to the group.
assignment[grade_group_students_individually]
integer
If this is a group assignment, teachers have the options to grade students individually. If false, Canvas will apply the assignment’s score to each member of the group. If true, the teacher can manually assign scores to each member of the group.
assignment[external_tool_tag_attributes]
string
Hash of external tool parameters if submission_types is [“external_tool”]. See Assignment object definition for format.
assignment[points_possible]
number
The maximum points possible on the assignment.
assignment[grading_type]
string
The strategy used for grading the assignment. The assignment defaults to “points” if this field is omitted.
The day/time the assignment is due. Must be between the lock dates if there are lock dates. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
assignment[lock_at]
DateTime
The day/time the assignment is locked after. Must be after the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
assignment[unlock_at]
DateTime
The day/time the assignment is unlocked. Must be before the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
assignment[description]
string
The assignment’s description, supports HTML.
assignment[assignment_group_id]
integer
The assignment group id to put the assignment in. Defaults to the top assignment group in the course.
assignment[assignment_overrides][]
AssignmentOverride
List of overrides for the assignment.
assignment[only_visible_to_overrides]
boolean
Whether this assignment is only visible to overrides (Only useful if ‘differentiated assignments’ account setting is on)
assignment[published]
boolean
Whether this assignment is published. (Only useful if ‘draft state’ account setting is on) Unpublished assignments are not visible to students.
assignment[grading_standard_id]
integer
The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course. This will update the grading_type for the course to ‘letter_grade’ unless it is already ‘gpa_scale’.
assignment[omit_from_final_grade]
boolean
Whether this assignment is counted towards a student’s final grade.
assignment[hide_in_gradebook]
boolean
Whether this assignment is shown in the gradebook.
assignment[quiz_lti]
boolean
Whether this assignment should use the Quizzes 2 LTI tool. Sets the submission type to ‘external_tool’ and configures the external tool attributes to use the Quizzes 2 LTI tool configured for this course. Has no effect if no Quizzes 2 LTI tool is configured.
assignment[moderated_grading]
boolean
Whether this assignment is moderated.
assignment[grader_count]
integer
The maximum number of provisional graders who may issue grades for this assignment. Only relevant for moderated assignments. Must be a positive value, and must be set to 1 if the course has fewer than two active instructors. Otherwise, the maximum value is the number of active instructors in the course minus one, or 10 if the course has more than 11 active instructors.
assignment[final_grader_id]
integer
The user ID of the grader responsible for choosing final grades for this assignment. Only relevant for moderated assignments.
assignment[grader_comments_visible_to_graders]
boolean
Boolean indicating if provisional graders’ comments are visible to other provisional graders. Only relevant for moderated assignments.
assignment[graders_anonymous_to_graders]
boolean
Boolean indicating if provisional graders’ identities are hidden from other provisional graders. Only relevant for moderated assignments.
assignment[graders_names_visible_to_final_grader]
boolean
Boolean indicating if provisional grader identities are visible to the the final grader. Only relevant for moderated assignments.
assignment[anonymous_grading]
boolean
Boolean indicating if the assignment is graded anonymously. If true, graders cannot see student identities.
assignment[allowed_attempts]
integer
The number of submission attempts allowed for this assignment. Set to -1 for unlimited attempts.
assignment[annotatable_attachment_id]
integer
The Attachment ID of the document being annotated.
Only applies when submission_types includes “student_annotation”.
assignment[asset_processors][]
Array
Document processors for this assignment. New document processors can only be added via the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication. Deletion of document processors (passing an empty array) is allowed via API.
assignment[peer_review][points_possible]
number
The maximum points possible for peer reviews.
assignment[peer_review][grading_type]
string
The strategy used for grading peer reviews. Defaults to “points” if this field is omitted.
The day/time the peer reviews are due. Must be between the lock dates if there are lock dates. Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z.
assignment[peer_review][lock_at]
DateTime
The day/time the peer reviews are locked after. Must be after the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z.
assignment[peer_review][unlock_at]
DateTime
The day/time the peer reviews are unlocked. Must be before the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z.
assignment[peer_review][peer_review_overrides][]
AssignmentOverride
List of overrides for the peer reviews.
string
Only applies if the assignment doesn’t have student submissions.
List of supported submission types for the assignment. Unless the assignment is allowing online submissions, the array should only have one element.
If not allowing online submissions, your options are:
If you are allowing online submissions, you can have one or many allowed submission types:
assignment[allowed_extensions][]
string
Allowed extensions if submission_types includes “online_upload”
Example:
assignment[turnitin_enabled]
boolean
Only applies when the Turnitin plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles Turnitin submissions for the assignment. Will be ignored if Turnitin is not available for the course.
assignment[vericite_enabled]
boolean
Only applies when the VeriCite plugin is enabled for a course and the submission_types array includes “online_upload”. Toggles VeriCite submissions for the assignment. Will be ignored if VeriCite is not available for the course.
assignment[turnitin_settings]
string
Settings to send along to turnitin. See Assignment object definition for format.
assignment[sis_assignment_id]
string
The sis id of the Assignment
assignment[integration_data]
string
Data used for SIS integrations. Requires admin-level token with the “Manage SIS” permission. JSON string required.
assignment[integration_id]
string
Unique ID from third party integrations
assignment[peer_reviews]
boolean
If submission_types does not include external_tool,discussion_topic, online_quiz, or on_paper, determines whether or not peer reviews will be turned on for the assignment.
assignment[automatic_peer_reviews]
boolean
Whether peer reviews will be assigned automatically by Canvas or if teachers must manually assign peer reviews. Does not apply if peer reviews are not enabled.
assignment[notify_of_update]
boolean
If true, Canvas will send a notification to students in the class notifying them that the content has changed.
assignment[group_category_id]
integer
If present, the assignment will become a group assignment assigned to the group.
assignment[grade_group_students_individually]
integer
If this is a group assignment, teachers have the options to grade students individually. If false, Canvas will apply the assignment’s score to each member of the group. If true, the teacher can manually assign scores to each member of the group.
assignment[external_tool_tag_attributes]
string
Hash of external tool parameters if submission_types is [“external_tool”]. See Assignment object definition for format.
assignment[points_possible]
number
The maximum points possible on the assignment.
assignment[grading_type]
string
The strategy used for grading the assignment. The assignment defaults to “points” if this field is omitted.
The day/time the assignment is due. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
assignment[lock_at]
DateTime
The day/time the assignment is locked after. Must be after the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
assignment[unlock_at]
DateTime
The day/time the assignment is unlocked. Must be before the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z.
assignment[description]
string
The assignment’s description, supports HTML.
assignment[assignment_group_id]
integer
The assignment group id to put the assignment in. Defaults to the top assignment group in the course.
assignment[assignment_overrides][]
AssignmentOverride
List of overrides for the assignment. If the assignment[assignment_overrides] key is absent, any existing overrides are kept as is. If the assignment[assignment_overrides] key is present, existing overrides are updated or deleted (and new ones created, as necessary) to match the provided list.
assignment[only_visible_to_overrides]
boolean
Whether this assignment is only visible to overrides (Only useful if ‘differentiated assignments’ account setting is on)
assignment[published]
boolean
Whether this assignment is published. (Only useful if ‘draft state’ account setting is on) Unpublished assignments are not visible to students.
assignment[grading_standard_id]
integer
The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course. This will update the grading_type for the course to ‘letter_grade’ unless it is already ‘gpa_scale’.
assignment[omit_from_final_grade]
boolean
Whether this assignment is counted towards a student’s final grade.
assignment[hide_in_gradebook]
boolean
Whether this assignment is shown in the gradebook.
assignment[moderated_grading]
boolean
Whether this assignment is moderated.
assignment[grader_count]
integer
The maximum number of provisional graders who may issue grades for this assignment. Only relevant for moderated assignments. Must be a positive value, and must be set to 1 if the course has fewer than two active instructors. Otherwise, the maximum value is the number of active instructors in the course minus one, or 10 if the course has more than 11 active instructors.
assignment[final_grader_id]
integer
The user ID of the grader responsible for choosing final grades for this assignment. Only relevant for moderated assignments.
assignment[grader_comments_visible_to_graders]
boolean
Boolean indicating if provisional graders’ comments are visible to other provisional graders. Only relevant for moderated assignments.
assignment[graders_anonymous_to_graders]
boolean
Boolean indicating if provisional graders’ identities are hidden from other provisional graders. Only relevant for moderated assignments.
assignment[graders_names_visible_to_final_grader]
boolean
Boolean indicating if provisional grader identities are visible to the the final grader. Only relevant for moderated assignments.
assignment[anonymous_grading]
boolean
Boolean indicating if the assignment is graded anonymously. If true, graders cannot see student identities.
assignment[allowed_attempts]
integer
The number of submission attempts allowed for this assignment. Set to -1 or null for unlimited attempts.
assignment[annotatable_attachment_id]
integer
The Attachment ID of the document being annotated.
Only applies when submission_types includes “student_annotation”.
assignment[asset_processors][]
Array
Document processors for this assignment. New document processors can only be added via the interactive LTI Deep Linking flow (in a browser), not via API token or JWT authentication. Deletion of document processors (passing an empty array) is allowed via API.
assignment[force_updated_at]
boolean
If true, updated_at will be set even if no changes were made.
assignment[peer_review][points_possible]
number
The maximum points possible for peer reviews.
assignment[peer_review][grading_type]
string
The strategy used for grading peer reviews. Defaults to “points” if this field is omitted.
The day/time the peer reviews are due. Must be between the lock dates if there are lock dates. Accepts times in ISO 8601 format, e.g. 2025-08-20T12:10:00Z.
assignment[peer_review][lock_at]
DateTime
The day/time the peer reviews are locked after. Must be after the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2025-08-25T12:10:00Z.
assignment[peer_review][unlock_at]
DateTime
The day/time the peer reviews are unlocked. Must be before the due date if there is a due date. Accepts times in ISO 8601 format, e.g. 2025-08-15T12:10:00Z.
assignment[peer_review][peer_review_overrides][]
AssignmentOverride
List of overrides for the peer reviews. When updating overrides:
Include “id” to update an existing override
assignment[submission_types][]
string
[DEPRECATED] Effective 2021-05-26 (notice given 2021-02-18)
Only applies if the assignment doesn’t have student submissions.
integer
The ID of the override’s target group. If present, the following conditions must be met for the override to be successful:
the assignment MUST be a group assignment (a group_category_id is assigned to it)
assignment_override[course_section_id]
integer
The ID of the override’s target section. If present, must identify an active section of the assignment’s course not already targetted by a different override.
assignment_override[due_at]
DateTime
The day/time the overridden assignment is due. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect due date. May be present but null to indicate the override removes any previous due date.
assignment_override[unlock_at]
DateTime
The day/time the overridden assignment becomes unlocked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the unlock date. May be present but null to indicate the override removes any previous unlock date.
assignment_override[lock_at]
DateTime
The day/time the overridden assignment becomes locked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the lock date. May be present but null to indicate the override removes any previous lock date.
DateTime
The day/time the overridden assignment is due. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect due date. May be present but null to indicate the override removes any previous due date.
assignment_override[unlock_at]
DateTime
The day/time the overridden assignment becomes unlocked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the unlock date. May be present but null to indicate the override removes any previous unlock date.
assignment_override[lock_at]
DateTime
The day/time the overridden assignment becomes locked. Accepts times in ISO 8601 format, e.g. 2014-10-21T18:48:00Z. If absent, this override will not affect the lock date. May be present but null to indicate the override removes any previous lock date.
include[]
string
Optional information to include with each assignment:
submission
The current user’s current Submission
assignment_visibility
An array of ids of students who can see the assignment
all_dates
An array of AssignmentDate structures, one for each override, and also a base if the assignment has an “Everyone” / “Everyone Else” date
overrides
An array of AssignmentOverride structures
observed_users
An array of submissions for observed users
can_edit
an extra Boolean value will be included with each Assignment (and AssignmentDate if all_dates is supplied) to indicate whether the caller can edit the assignment or date. Moderated grading and closed grading periods may restrict a user’s ability to edit an assignment.
score_statistics
An object containing min, max, and mean score on this assignment. This will not be included for students if there are less than 5 graded assignments or if disabled by the instructor. Only valid if ‘submission’ is also included.
The partial title of the assignments to match and return.
result_type
string
Optional information: When the root account has the feature newquizzes_on_quiz_page enabled and this argument is set to “Quiz” the response will be serialized into a quiz format; When this argument isn’t specified the response will be serialized into an assignment format;
Allowed values: Quiz
include[]
string
Associations to include with the assignment. The “assignment_visibility” option requires that the Differentiated Assignments course feature be turned on. If “observed_users” is passed, submissions for observed users will also be included. For “score_statistics” to be included, the “submission” option must also be set. The “peer_review” option requires that the Peer Review Allocation and Grading course feature be turned on.
Apply assignment overrides to the assignment, defaults to true.
assignment[name]
Required string
The assignment name.
assignment[position]
integer
The position of this assignment in the group when displaying assignment lists.
assignment[name]
string
The assignment name.
assignment[position]
integer
The position of this assignment in the group when displaying assignment lists.
assignment_override[student_ids][]
integer
The IDs of the override’s target students. If present, the IDs must each identify a user with an active student enrollment in the course that is not already targetted by a different adhoc override.
assignment_override[title]
string
The title of the adhoc assignment override. Required if student_ids is present, ignored otherwise (the title is set to the name of the targetted group or section instead).
assignment_override[student_ids][]
integer
The IDs of the override’s target students. If present, the IDs must each identify a user with an active student enrollment in the course that is not already targetted by a different adhoc override. Ignored unless the override being updated is adhoc.
assignment_override[title]
string
The title of an adhoc assignment override. Ignored unless the override being updated is adhoc.
{
// URL to the external tool
"url": "http://instructure.com",
// Whether or not there is a new tab for the external tool
"new_tab": false,
// the identifier for this tool_tag
"resource_link_id": "ab81173af98b8c33e66a"
}
{
// Asset string for the object causing the lock
"asset_string": "assignment_4",
// (Optional) Time at which this was/will be unlocked. Must be before the due
// date.
"unlock_at": "2013-01-01T00:00:00-06:00",
// (Optional) Time at which this was/will be locked. Must be after the due date.
"lock_at": "2013-02-01T00:00:00-06:00",
// (Optional) Context module causing the lock.
"context_module": "{}",
"manually_locked": true
}
{
"points": 10,
// The id of rubric criteria.
"id": "crit1",
// (Optional) The id of the learning outcome this criteria uses, if any.
"learning_outcome_id": "1234",
// (Optional) The 3rd party vendor's GUID for the outcome this criteria
// references, if any.
"vendor_guid": "abdsfjasdfne3jsdfn2",
"description": "Criterion 1",
"long_description": "Criterion 1 more details",
"criterion_use_range": true,
"ratings": null,
"ignore_for_scoring": true
}
// Object representing a due date for an assignment or quiz. If the due date
// came from an assignment override, it will have an 'id' field.
{
// (Optional, missing if 'base' is present) id of the assignment override this
// date represents
"id": 1,
// (Optional, present if 'id' is missing) whether this date represents the
// assignment's or quiz's default due date
"base": true,
"title": "Summer Session",
// The due date for the assignment. Must be between the unlock date and the lock
// date if there are lock dates
"due_at": "2013-08-28T23:59:00-06:00",
// The unlock date for the assignment. Must be before the due date if there is a
// due date.
"unlock_at": "2013-08-01T00:00:00-06:00",
// The lock date for the assignment. Must be after the due date if there is a
// due date.
"lock_at": "2013-08-31T23:59:00-06:00"
}
// Used by Assignment model
{
// The section ID
"section_id": "123456",
// Number of submissions that need grading
"needs_grading_count": 5
}
// Used by Assignment model
{
// Min score
"min": 1,
// Max score
"max": 10,
// Mean score
"mean": 6,
// Upper quartile score
"upper_q": 10,
// Median score
"median": 6,
// Lower quartile score
"lower_q": 1
}
{
// the ID of the assignment
"id": 4,
// the name of the assignment
"name": "some assignment",
// the assignment description, in an HTML fragment
"description": "<p>Do the following:</p>...",
// The time at which this assignment was originally created
"created_at": "2012-07-01T23:59:00-06:00",
// The time at which this assignment was last modified in any way
"updated_at": "2012-07-01T23:59:00-06:00",
// the due date for the assignment. returns null if not present. NOTE: If this
// assignment has assignment overrides, this field will be the due date as it
// applies to the user requesting information from the API.
"due_at": "2012-07-01T23:59:00-06:00",
// the lock date (assignment is locked after this date). returns null if not
// present. NOTE: If this assignment has assignment overrides, this field will
// be the lock date as it applies to the user requesting information from the
// API.
"lock_at": "2012-07-01T23:59:00-06:00",
// the unlock date (assignment is unlocked after this date) returns null if not
// present NOTE: If this assignment has assignment overrides, this field will be
// the unlock date as it applies to the user requesting information from the
// API.
"unlock_at": "2012-07-01T23:59:00-06:00",
// whether this assignment has overrides
"has_overrides": true,
// (Optional) all dates associated with the assignment, if applicable
"all_dates": null,
// the ID of the course the assignment belongs to
"course_id": 123,
// the URL to the assignment's web page
"html_url": "https://...",
// the URL to download all submissions as a zip
"submissions_download_url": "https://example.com/courses/:course_id/assignments/:id/submissions?zip=1",
// the ID of the assignment's group
"assignment_group_id": 2,
// Boolean flag indicating whether the assignment requires a due date based on
// the account level setting
"due_date_required": true,
// Allowed file extensions, which take effect if submission_types includes
// 'online_upload'.
"allowed_extensions": ["docx", "ppt"],
// An integer indicating the maximum length an assignment's name may be
"max_name_length": 15,
// Boolean flag indicating whether or not Turnitin has been enabled for the
// assignment. NOTE: This flag will not appear unless your account has the
// Turnitin plugin available
"turnitin_enabled": true,
// Boolean flag indicating whether or not VeriCite has been enabled for the
// assignment. NOTE: This flag will not appear unless your account has the
// VeriCite plugin available
"vericite_enabled": true,
// Settings to pass along to turnitin to control what kinds of matches should be
// considered. originality_report_visibility can be 'immediate',
// 'after_grading', 'after_due_date', or 'never' exclude_small_matches_type can
// be null, 'percent', 'words' exclude_small_matches_value: - if type is null,
// this will be null also - if type is 'percent', this will be a number between
// 0 and 100 representing match size to exclude as a percentage of the document
// size. - if type is 'words', this will be number > 0 representing how many
// words a match must contain for it to be considered NOTE: This flag will not
// appear unless your account has the Turnitin plugin available
"turnitin_settings": null,
// If this is a group assignment, boolean flag indicating whether or not
// students will be graded individually.
"grade_group_students_individually": false,
// (Optional) assignment's settings for external tools if submission_types
// include 'external_tool'. Only url and new_tab are included (new_tab defaults
// to false). Use the 'External Tools' API if you need more information about
// an external tool.
"external_tool_tag_attributes": null,
// Boolean indicating if peer reviews are required for this assignment
"peer_reviews": false,
// Boolean indicating peer reviews are assigned automatically. If false, the
// teacher is expected to manually assign peer reviews.
"automatic_peer_reviews": false,
// Integer representing the amount of reviews each user is assigned. NOTE: This
// key is NOT present unless you have automatic_peer_reviews set to true.
"peer_review_count": 0,
// String representing a date the reviews are due by. Must be a date that occurs
// after the default due date. If blank, or date is not after the assignment's
// due date, the assignment's due date will be used. NOTE: This key is NOT
// present unless you have automatic_peer_reviews set to true.
"peer_reviews_assign_at": "2012-07-01T23:59:00-06:00",
// Boolean representing whether or not members from within the same group on a
// group assignment can be assigned to peer review their own group's work
"intra_group_peer_reviews": false,
// The ID of the assignment’s group set, if this is a group assignment. For
// group discussions, set group_category_id on the discussion topic, not the
// linked assignment.
"group_category_id": 1,
// if the requesting user has grading rights, the number of submissions that
// need grading.
"needs_grading_count": 17,
// if the requesting user has grading rights and the
// 'needs_grading_count_by_section' flag is specified, the number of submissions
// that need grading split out by section. NOTE: This key is NOT present unless
// you pass the 'needs_grading_count_by_section' argument as true. ANOTHER
// NOTE: it's possible to be enrolled in multiple sections, and if a student is
// setup that way they will show an assignment that needs grading in multiple
// sections (effectively the count will be duplicated between sections)
"needs_grading_count_by_section": [{"section_id":"123456","needs_grading_count":5}, {"section_id":"654321","needs_grading_count":0}],
// the sorting order of the assignment in the group
"position": 1,
// (optional, present if Sync Grades to SIS feature is enabled)
"post_to_sis": true,
// (optional, Third Party unique identifier for Assignment)
"integration_id": "12341234",
// (optional, Third Party integration data for assignment)
"integration_data": {"5678":"0954"},
// the maximum points possible for the assignment
"points_possible": 12.0,
// the types of submissions allowed for this assignment list containing one or
// more of the following: 'discussion_topic', 'online_quiz', 'on_paper', 'none',
// 'external_tool', 'online_text_entry', 'online_url', 'online_upload',
// 'media_recording', 'student_annotation'
"submission_types": ["online_text_entry"],
// If true, the assignment has been submitted to by at least one student
"has_submitted_submissions": true,
// The type of grading the assignment receives; one of 'pass_fail', 'percent',
// 'letter_grade', 'gpa_scale', 'points'
"grading_type": "points",
// The id of the grading standard being applied to this assignment. Valid if
// grading_type is 'letter_grade' or 'gpa_scale'.
"grading_standard_id": null,
// Whether the assignment is published
"published": true,
// Whether the assignment's 'published' state can be changed to false. Will be
// false if there are student submissions for the assignment.
"unpublishable": false,
// Whether the assignment is only visible to overrides.
"only_visible_to_overrides": false,
// Whether or not this is locked for the user.
"locked_for_user": false,
// (Optional) Information for the user about the lock. Present when
// locked_for_user is true.
"lock_info": null,
// (Optional) An explanation of why this is locked for the user. Present when
// locked_for_user is true.
"lock_explanation": "This assignment is locked until September 1 at 12:00am",
// (Optional) id of the associated quiz (applies only when submission_types is
// ['online_quiz'])
"quiz_id": 620,
// (Optional) whether anonymous submissions are accepted (applies only to quiz
// assignments)
"anonymous_submissions": false,
// (Optional) the DiscussionTopic associated with the assignment, if applicable
"discussion_topic": null,
// (Optional) Boolean indicating if assignment will be frozen when it is copied.
// NOTE: This field will only be present if the AssignmentFreezer plugin is
// available for your account.
"freeze_on_copy": false,
// (Optional) Boolean indicating if assignment is frozen for the calling user.
// NOTE: This field will only be present if the AssignmentFreezer plugin is
// available for your account.
"frozen": false,
// (Optional) Array of frozen attributes for the assignment. Only account
// administrators currently have permission to change an attribute in this list.
// Will be empty if no attributes are frozen for this assignment. Possible
// frozen attributes are: title, description, lock_at, points_possible,
// grading_type, submission_types, assignment_group_id, allowed_extensions,
// group_category_id, notify_of_update, peer_reviews NOTE: This field will only
// be present if the AssignmentFreezer plugin is available for your account.
"frozen_attributes": ["title"],
// (Optional) If 'submission' is included in the 'include' parameter, includes a
// Submission object that represents the current user's (user who is requesting
// information from the api) current submission for the assignment. See the
// Submissions API for an example response. If the user does not have a
// submission, this key will be absent.
"submission": null,
// (Optional) If true, the rubric is directly tied to grading the assignment.
// Otherwise, it is only advisory. Included if there is an associated rubric.
"use_rubric_for_grading": true,
// (Optional) An object describing the basic attributes of the rubric, including
// the point total. Included if there is an associated rubric.
"rubric_settings": {"points_possible":"12"},
// (Optional) A list of scoring criteria and ratings for each rubric criterion.
// Included if there is an associated rubric.
"rubric": null,
// (Optional) If 'assignment_visibility' is included in the 'include' parameter,
// includes an array of student IDs who can see this assignment.
"assignment_visibility": [137, 381, 572],
// (Optional) If 'overrides' is included in the 'include' parameter, includes an
// array of assignment override objects.
"overrides": null,
// (Optional) If true, the assignment will be omitted from the student's final
// grade
"omit_from_final_grade": true,
// (Optional) If true, the assignment will not be shown in any gradebooks
"hide_in_gradebook": true,
// Boolean indicating if the assignment is moderated.
"moderated_grading": true,
// The maximum number of provisional graders who may issue grades for this
// assignment. Only relevant for moderated assignments. Must be a positive
// value, and must be set to 1 if the course has fewer than two active
// instructors. Otherwise, the maximum value is the number of active instructors
// in the course minus one, or 10 if the course has more than 11 active
// instructors.
"grader_count": 3,
// The user ID of the grader responsible for choosing final grades for this
// assignment. Only relevant for moderated assignments.
"final_grader_id": 3,
// Boolean indicating if provisional graders' comments are visible to other
// provisional graders. Only relevant for moderated assignments.
"grader_comments_visible_to_graders": true,
// Boolean indicating if provisional graders' identities are hidden from other
// provisional graders. Only relevant for moderated assignments with
// grader_comments_visible_to_graders set to true.
"graders_anonymous_to_graders": true,
// Boolean indicating if provisional grader identities are visible to the final
// grader. Only relevant for moderated assignments.
"grader_names_visible_to_final_grader": true,
// Boolean indicating if the assignment is graded anonymously. If true, graders
// cannot see student identities.
"anonymous_grading": true,
// The number of submission attempts a student can make for this assignment. -1
// is considered unlimited.
"allowed_attempts": 2,
// Whether the assignment has manual posting enabled. Only relevant for courses
// using New Gradebook.
"post_manually": true,
// (Optional) If 'score_statistics' and 'submission' are included in the
// 'include' parameter and statistics are available, includes the min, max, and
// mode for this assignment
"score_statistics": null,
// (Optional) If retrieving a single assignment and 'can_submit' is included in
// the 'include' parameter, flags whether user has the right to submit the
// assignment (i.e. checks enrollment dates, submission types, locked status,
// attempts remaining, etc...). Including 'can submit' automatically includes
// 'submission' in the include parameter. Not available when observed_users are
// included.
"can_submit": true,
// (Optional) The academic benchmark(s) associated with the assignment or the
// assignment's rubric. Only included if 'ab_guid' is included in the 'include'
// parameter.
"ab_guid": ["ABCD", "EFGH"],
// The id of the attachment to be annotated by students. Relevant only if
// submission_types includes 'student_annotation'.
"annotatable_attachment_id": null,
// (Optional) Boolean indicating whether student names are anonymized
"anonymize_students": false,
// (Optional) Boolean indicating whether the Respondus LockDown Browser® is
// required for this assignment.
"require_lockdown_browser": false,
// (Optional) Boolean indicating whether this assignment has important dates.
"important_dates": false,
// (Optional, Deprecated) Boolean indicating whether notifications are muted for
// this assignment.
"muted": false,
// Boolean indicating whether peer reviews are anonymous.
"anonymous_peer_reviews": false,
// Boolean indicating whether instructor anotations are anonymous.
"anonymous_instructor_annotations": false,
// Boolean indicating whether this assignment has graded submissions.
"graded_submissions_exist": false,
// Boolean indicating whether this is a quiz lti assignment.
"is_quiz_assignment": false,
// Boolean indicating whether this assignment is in a closed grading period.
"in_closed_grading_period": false,
// Boolean indicating whether this assignment can be duplicated.
"can_duplicate": false,
// If this assignment is a duplicate, it is the original assignment's course_id
"original_course_id": 4,
// If this assignment is a duplicate, it is the original assignment's id
"original_assignment_id": 4,
// If this assignment is a duplicate, it is the original assignment's
// lti_resource_link_id
"original_lti_resource_link_id": 4,
// If this assignment is a duplicate, it is the original assignment's name
"original_assignment_name": "some assignment",
// If this assignment is a duplicate, it is the original assignment's quiz_id
"original_quiz_id": 4,
// String indicating what state this assignment is in.
"workflow_state": "unpublished"
}
{
// The user's ID
"id": "123456",
// The user's name
"name": "Dankey Kang"
}
{
// the ID of the assignment override
"id": 4,
// the ID of the assignment the override applies to (present if the override
// applies to an assignment)
"assignment_id": 123,
// the ID of the quiz the override applies to (present if the override applies
// to a quiz)
"quiz_id": 123,
// the ID of the module the override applies to (present if the override applies
// to a module)
"context_module_id": 123,
// the ID of the discussion the override applies to (present if the override
// applies to an ungraded discussion)
"discussion_topic_id": 123,
// the ID of the page the override applies to (present if the override applies
// to a page)
"wiki_page_id": 123,
// the ID of the file the override applies to (present if the override applies
// to a file)
"attachment_id": 123,
// the IDs of the override's target students (present if the override targets an
// ad-hoc set of students)
"student_ids": [1, 2, 3],
// the ID of the override's target group (present if the override targets a
// group and the assignment is a group assignment)
"group_id": 2,
// the ID of the overrides's target section (present if the override targets a
// section)
"course_section_id": 1,
// the title of the override
"title": "an assignment override",
// the overridden due at (present if due_at is overridden)
"due_at": "2012-07-01T23:59:00-06:00",
// the overridden all day flag (present if due_at is overridden)
"all_day": true,
// the overridden all day date (present if due_at is overridden)
"all_day_date": "2012-07-01",
// the overridden unlock at (present if unlock_at is overridden)
"unlock_at": "2012-07-01T23:59:00-06:00",
// the overridden lock at, if any (present if lock_at is overridden)
"lock_at": "2012-07-01T23:59:00-06:00"
}
Returns the paginated list of active courses for the current user.
Request Parameters:
Parameter
Type
Description
Returns a list of objects.
GET /api/v1/users/:user_id/courses
Scope:url:GET|/api/v1/users/:user_id/courses
Returns a paginated list of active courses for this user. To view the course list for a user other than yourself, you must be either an observer of that user or an administrator.
Request Parameters:
Parameter
Type
Description
Returns a list of objects.
GET /api/v1/courses/:course_id/users/:user_id/progress
Return progress information for the user and course
You can supply self as the user_id to query your own progress in a course. To query another user’s progress, you must be a teacher in the course, an administrator, or a linked observer of the user.
Returns the paginated list of users in this course, ordered by how recently they have logged in. The records include the ‘last_login’ field which contains a timestamp of the last time that user logged into canvas. The querying user must have the ‘View usage reports’ permission.
Returns a paginated list of users you can share content with. Requires the content share feature and the user must have the manage content permission for the course.
Returns information for a test student in this course. Creates a test student if one does not already exist for the course. The caller must have permission to access the course’s student view.
Accepts the same include[] parameters as the list action plus:
Request Parameters:
Parameter
Type
Description
Returns a object.
PUT /api/v1/courses/:id
Scope:url:PUT|/api/v1/courses/:id
Update an existing course.
Arguments are the same as Courses#create, with a few exceptions (enroll_me).
If a user has content management rights, but not full course editing rights, the only attribute editable through this endpoint will be “syllabus_body”
If an account has set prevent_course_availability_editing_by_teachers, a teacher cannot change course[start_at], course[conclude_at], or course[restrict_enrollments_to_course_dates] here.
For each assignment in the course, returns each assigned student’s ID and their corresponding due date along with some grading period data. Returns a collection with keys representing assignment IDs and values as a collection containing keys representing student IDs and values representing the student’s effective due_at, the grading_period_id of which the due_at falls in, and whether or not the grading period is closed (in_closed_grading_period)
The list of assignment IDs for which effective student due dates are requested. If not provided, all assignments in the course will be used.
Copies content from one course into another. The default is to copy all course content. You can control specific types to copy by using either the ‘except’ option or the ‘only’ option.
The response is the same as the course copy status endpoint
Request Parameters:
Parameter
Type
Description
This documentation is generated directly from the Canvas LMS source code, available .
integer
When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the or a built_in role type of ‘StudentEnrollment’, ‘TeacherEnrollment’, ‘TaEnrollment’, ‘ObserverEnrollment’, or ‘DesignerEnrollment’.
enrollment_state
string
When set, only return courses where the user has an enrollment with the given state. This will respect section/course/term date overrides.
When set, only return courses that are not configured as blueprint courses.
include[]
string
“needs_grading_count”: Optional information to include with each Course. When needs_grading_count is given, and the current user has grading rights, the total number of submissions needing grading for all assignments is returned.
“syllabus_body”: Optional information to include with each Course. When syllabus_body is given the user-generated html for the course syllabus is returned.
state[]
string
If set, only return courses that are in the given state(s). By default, “available” is returned for students and observers, and anything except “deleted”, for all other enrollment types
If set, only include courses associated with this account
DateTime
Course start date in ISO8601 format, e.g. 2011-01-01T01:00Z This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true.
course[end_at]
DateTime
Course end date in ISO8601 format. e.g. 2011-01-01T01:00Z This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true.
course[license]
string
The name of the licensing. Should be one of the following abbreviations (a descriptive name is included in parenthesis for reference):
‘private’ (Private Copyrighted)
course[is_public]
boolean
Set to true if course is public to both authenticated and unauthenticated users.
course[is_public_to_auth_users]
boolean
Set to true if course is public only to authenticated users.
course[public_syllabus]
boolean
Set to true to make the course syllabus public.
course[public_syllabus_to_auth]
boolean
Set to true to make the course syllabus public for authenticated users.
course[public_description]
string
A publicly visible description of the course.
course[allow_student_wiki_edits]
boolean
If true, students will be able to modify the course wiki.
course[allow_wiki_comments]
boolean
If true, course members will be able to comment on wiki pages.
course[allow_student_forum_attachments]
boolean
If true, students can attach files to forum posts.
course[open_enrollment]
boolean
Set to true if the course is open enrollment.
course[self_enrollment]
boolean
Set to true if the course is self enrollment.
course[restrict_enrollments_to_course_dates]
boolean
Set to true to restrict user enrollments to the start and end dates of the course. This value must be set to true in order to specify a course start date and/or end date.
course[term_id]
string
The unique ID of the term to create to course in.
course[sis_course_id]
string
The unique SIS identifier.
course[integration_id]
string
The unique Integration identifier.
course[hide_final_grades]
boolean
If this option is set to true, the totals in student grades summary will be hidden.
course[apply_assignment_group_weights]
boolean
Set to true to weight final grade based on assignment groups percentages.
course[time_zone]
string
The time zone for the course. Allowed time zones are or friendlier .
offer
boolean
If this option is set to true, the course will be available to students immediately.
enroll_me
boolean
Set to true to enroll the current user as the teacher.
skip_course_template
boolean
If this option is set to true, the template of the account will not be applied to this course It means copy_from_course_template will not be executed. This option is thought for a course copy.
course[default_view]
string
The type of page that users will see when they first visit the course
‘feed’ Recent Activity Dashboard
course[syllabus_body]
string
The syllabus body for the course
course[grading_standard_id]
integer
The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course.
course[grade_passback_setting]
string
Optional. The grade_passback_setting for the course. Only ‘nightly_sync’, ‘disabled’, and ” are allowed
course[course_format]
string
Optional. Specifies the format of the course. (Should be ‘on_campus’, ‘online’, or ‘blended’)
course[post_manually]
boolean
Default is false. When true, all grades in the course must be posted manually, and will not be automatically posted. When false, all grades in the course will be automatically posted.
enable_sis_reactivation
boolean
When true, will first try to re-activate a deleted course with matching sis_course_id if possible.
string
When set, only return users where the user is enrolled as this type. “student_view” implies include[]=test_student. This argument is ignored if enrollment_role is given.
Allowed values: teacher, student, student_view, ta, observer, designer
enrollment_role
string
Deprecated When set, only return users enrolled with the specified course-level role. This can be a role created with the or a base role type of ‘StudentEnrollment’, ‘TeacherEnrollment’, ‘TaEnrollment’, ‘ObserverEnrollment’, or ‘DesignerEnrollment’.
enrollment_role_id
integer
When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the or a built_in role id with type ‘StudentEnrollment’, ‘TeacherEnrollment’, ‘TaEnrollment’, ‘ObserverEnrollment’, or ‘DesignerEnrollment’.
section_ids[]
integer
When set, only return users who are enrolled in the given section(s).
include[]
string
“enrollments”:
Optionally include with each Course the user’s current and invited enrollments. If the user is enrolled as a student, and the account has permission to manage or view all grades, each enrollment will include a ‘grades’ key with ‘current_score’, ‘final_score’, ‘current_grade’ and ‘final_grade’ values.
user_id
string
If this parameter is given and it corresponds to a user in the course, the page parameter will be ignored and the page containing the specified user will be returned instead.
user_ids[]
integer
If included, the course users set will only include users with IDs specified by the param. Note: this will not work in conjunction with the “user_id” argument but multiple user_ids can be included.
enrollment_state[]
string
When set, only return users where the enrollment workflow state is of one of the given types. “active” and “invited” enrollments are returned by default.
Let students edit or delete their own discussion replies
allow_student_organized_groups
boolean
Let students organize their own groups
allow_student_discussion_reporting
boolean
Let students report offensive discussion content
allow_student_anonymous_discussion_topics
boolean
Let students create anonymous discussion topics
filter_speed_grader_by_student_group
boolean
Filter SpeedGrader to only the selected student group
hide_final_grades
boolean
Hide totals in student grades summary
hide_distribution_graphs
boolean
Hide grade distribution graphs from students
hide_sections_on_course_users_page
boolean
Disallow students from viewing students in sections they do not belong to
lock_all_announcements
boolean
Disable comments on announcements
usage_rights_required
boolean
Copyright and license information must be provided for files before they are published.
restrict_student_past_view
boolean
Restrict students from viewing courses after end date
restrict_student_future_view
boolean
Restrict students from viewing courses before start date
show_announcements_on_home_page
boolean
Show the most recent announcements on the Course home page (if a Wiki, defaults to five announcements, configurable via home_page_announcement_limit). Canvas for Elementary subjects ignore this setting.
home_page_announcement_limit
integer
Limit the number of announcements on the home page if enabled via show_announcements_on_home_page
syllabus_course_summary
boolean
Show the course summary (list of assignments and calendar events) on the syllabus page. Default is true.
default_due_time
string
Set the default due time for assignments. This is the time that will be pre-selected in the Canvas user interface when setting a due date for an assignment. It does not change when any existing assignment is due. It should be given in 24-hour HH:MM:SS format. The default is “23:59:59”. Use “inherit” to inherit the account setting.
conditional_release
boolean
Enable or disable individual learning paths for students based on assessment
string
The course code for the course.
course[start_at]
DateTime
Course start date in ISO8601 format, e.g. 2011-01-01T01:00Z This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true, or the course is already published.
course[end_at]
DateTime
Course end date in ISO8601 format. e.g. 2011-01-01T01:00Z This value is ignored unless ‘restrict_enrollments_to_course_dates’ is set to true.
course[license]
string
The name of the licensing. Should be one of the following abbreviations (a descriptive name is included in parenthesis for reference):
‘private’ (Private Copyrighted)
course[is_public]
boolean
Set to true if course is public to both authenticated and unauthenticated users.
course[is_public_to_auth_users]
boolean
Set to true if course is public only to authenticated users.
course[public_syllabus]
boolean
Set to true to make the course syllabus public.
course[public_syllabus_to_auth]
boolean
Set to true to make the course syllabus to public for authenticated users.
course[public_description]
string
A publicly visible description of the course.
course[allow_student_wiki_edits]
boolean
If true, students will be able to modify the course wiki.
course[allow_wiki_comments]
boolean
If true, course members will be able to comment on wiki pages.
course[allow_student_forum_attachments]
boolean
If true, students can attach files to forum posts.
course[open_enrollment]
boolean
Set to true if the course is open enrollment.
course[self_enrollment]
boolean
Set to true if the course is self enrollment.
course[restrict_enrollments_to_course_dates]
boolean
Set to true to restrict user enrollments to the start and end dates of the course. Setting this value to false will remove the course end date (if it exists), as well as the course start date (if the course is unpublished).
course[term_id]
integer
The unique ID of the term to create to course in.
course[sis_course_id]
string
The unique SIS identifier.
course[integration_id]
string
The unique Integration identifier.
course[hide_final_grades]
boolean
If this option is set to true, the totals in student grades summary will be hidden.
course[time_zone]
string
The time zone for the course. Allowed time zones are or friendlier .
course[apply_assignment_group_weights]
boolean
Set to true to weight final grade based on assignment groups percentages.
course[storage_quota_mb]
integer
Set the storage quota for the course, in megabytes. The caller must have the “Manage storage quotas” account permission.
offer
boolean
If this option is set to true, the course will be available to students immediately.
course[event]
string
The action to take on each course.
‘claim’ makes a course no longer visible to students. This action is also called “unpublish” on the web site. A course cannot be unpublished if students have received graded submissions.
course[default_view]
string
The type of page that users will see when they first visit the course
‘feed’ Recent Activity Dashboard
course[syllabus_body]
string
The syllabus body for the course
course[syllabus_course_summary]
boolean
Optional. Indicates whether the Course Summary (consisting of the course’s assignments and calendar events) is displayed on the syllabus page. Defaults to true.
course[grading_standard_id]
integer
The grading standard id to set for the course. If no value is provided for this argument the current grading_standard will be un-set from this course.
course[grade_passback_setting]
string
Optional. The grade_passback_setting for the course. Only ‘nightly_sync’ and ” are allowed
course[course_format]
string
Optional. Specifies the format of the course. (Should be either ‘on_campus’ or ‘online’)
course[image_id]
integer
This is a file ID corresponding to an image file in the course that will be used as the course image. This will clear the course’s image_url setting if set. If you attempt to provide image_url and image_id in a request it will fail.
course[image_url]
string
This is a URL to an image to be used as the course image. This will clear the course’s image_id setting if set. If you attempt to provide image_url and image_id in a request it will fail.
course[remove_image]
boolean
If this option is set to true, the course image url and course image ID are both set to nil
course[remove_banner_image]
boolean
If this option is set to true, the course banner image url and course banner image ID are both set to nil
course[blueprint]
boolean
Sets the course as a blueprint course.
course[blueprint_restrictions]
BlueprintRestriction
Sets a default set to apply to blueprint course objects when restricted, unless use_blueprint_restrictions_by_object_type is enabled. See the documentation
course[use_blueprint_restrictions_by_object_type]
boolean
When enabled, the blueprint_restrictions parameter will be ignored in favor of the blueprint_restrictions_by_object_type parameter
course[blueprint_restrictions_by_object_type]
multiple BlueprintRestrictions
Allows setting multiple to apply to blueprint course objects of the matching type when restricted. The possible object types are “assignment”, “attachment”, “discussion_topic”, “quiz” and “wiki_page”. Example usage:
course[homeroom_course]
boolean
Sets the course as a homeroom course. The setting takes effect only when the course is associated with a Canvas for Elementary-enabled account.
course[sync_enrollments_from_homeroom]
string
Syncs enrollments from the homeroom that is set in homeroom_course_id. The setting only takes effect when the course is associated with a Canvas for Elementary-enabled account and sync_enrollments_from_homeroom is enabled.
course[homeroom_course_id]
string
Sets the Homeroom Course id to be used with sync_enrollments_from_homeroom. The setting only takes effect when the course is associated with a Canvas for Elementary-enabled account and sync_enrollments_from_homeroom is enabled.
course[template]
boolean
Enable or disable the course as a template that can be selected by an account
course[course_color]
string
Sets a color in hex code format to be associated with the course. The setting takes effect only when the course is associated with a Canvas for Elementary-enabled account.
course[friendly_name]
string
Set a friendly name for the course. If this is provided and the course is associated with a Canvas for Elementary account, it will be shown instead of the course name. This setting takes priority over course nicknames defined by individual users.
course[enable_course_paces]
boolean
Enable or disable Course Pacing for the course. This setting only has an effect when the Course Pacing feature flag is enabled for the sub-account. Otherwise, Course Pacing are always disabled.
course[conditional_release]
boolean
Enable or disable individual learning paths for students based on assessment
course[post_manually]
boolean
When true, all grades in the course will be posted manually. When false, all grades in the course will be automatically posted. Use with caution as this setting will override any assignment level post policy.
override_sis_stickiness
boolean
Default is true. If false, any fields containing “sticky” changes will not be updated. See SIS CSV Format documentation for information on which fields can have SIS stickiness
string
A list of the course content types to copy, all areas not listed will not be copied.
When set, only return courses where the user is enrolled as this type. For example, set to “teacher” to return only courses where the user is enrolled as a Teacher. This argument is ignored if enrollment_role is given.
Allowed values: teacher, student, ta, observer, designer
enrollment_role
string
Deprecated When set, only return courses where the user is enrolled with the specified course-level role. This can be a role created with the Add Role API or a base role type of ‘StudentEnrollment’, ‘TeacherEnrollment’, ‘TaEnrollment’, ‘ObserverEnrollment’, or ‘DesignerEnrollment’.
include[]
string
“needs_grading_count”: Optional information to include with each Course. When needs_grading_count is given, and the current user has grading rights, the total number of submissions needing grading for all assignments is returned.
“syllabus_body”: Optional information to include with each Course. When syllabus_body is given the user-generated html for the course syllabus is returned.
“public_description”: Optional information to include with each Course. When public_description is given the user-generated text for the course public description is returned.
“total_scores”: Optional information to include with each Course. When total_scores is given, any student enrollments will also include the fields ‘computed_current_score’, ‘computed_final_score’, ‘computed_current_grade’, and ‘computed_final_grade’ (see Enrollment documentation for more information on these fields). This argument is ignored if the course is configured to hide final grades.
“current_grading_period_scores”: Optional information to include with each Course. When current_grading_period_scores is given and total_scores is given, any student enrollments will also include the fields ‘has_grading_periods’, ‘totals_for_all_grading_periods_option’, ‘current_grading_period_title’, ‘current_grading_period_id’, current_period_computed_current_score’, ‘current_period_computed_final_score’, ‘current_period_computed_current_grade’, and ‘current_period_computed_final_grade’, as well as (if the user has permission) ‘current_period_unposted_current_score’, ‘current_period_unposted_final_score’, ‘current_period_unposted_current_grade’, and ‘current_period_unposted_final_grade’ (see Enrollment documentation for more information on these fields). In addition, when this argument is passed, the course will have a ‘has_grading_periods’ attribute on it. This argument is ignored if the course is configured to hide final grades or if the total_scores argument is not included.
“grading_periods”: Optional information to include with each Course. When grading_periods is given, a list of the grading periods associated with each course is returned.
“term”: Optional information to include with each Course. When term is given, the information for the enrollment term for each course is returned.
“account”: Optional information to include with each Course. When account is given, the account json for each course is returned.
“course_progress”: Optional information to include with each Course. When course_progress is given, each course will include a ‘course_progress’ object with the fields: ‘requirement_count’, an integer specifying the total number of requirements in the course, ‘requirement_completed_count’, an integer specifying the total number of requirements in this course that have been completed, and ‘next_requirement_url’, a string url to the next requirement item, and ‘completed_at’, the date the course was completed (null if incomplete). ‘next_requirement_url’ will be null if all requirements have been completed or the current module does not require sequential progress. “course_progress” will return an error message if the course is not module based or the user is not enrolled as a student in the course.
“sections”: Section enrollment information to include with each Course. Returns an array of hashes containing the section ID (id), section name (name), start and end dates (start_at, end_at), as well as the enrollment type (enrollment_role, e.g. ‘StudentEnrollment’).
“storage_quota_used_mb”: The amount of storage space used by the files in this course
“total_students”: Optional information to include with each Course. Returns an integer for the total amount of active and invited students.
“passback_status”: Include the grade passback_status
“favorites”: Optional information to include with each Course. Indicates if the user has marked the course as a favorite course.
“teachers”: Teacher information to include with each Course. Returns an array of hashes containing the information for each teacher in the course.
“observed_users”: Optional information to include with each Course. Will include data for observed users if the current user has an observer enrollment.
“tabs”: Optional information to include with each Course. Will include the list of tabs configured for each course. See the for more information.
“course_image”: Optional information to include with each Course. Returns course image url if a course image has been set.
“banner_image”: Optional information to include with each Course. Returns course banner image url if the course is a Canvas for Elementary subject and a banner image has been set.
“concluded”: Optional information to include with each Course. Indicates whether the course has been concluded, taking course and term dates into account.
“post_manually”: Optional information to include with each Course. Returns true if the course post policy is set to “Manually”. Returns false if the the course post policy is set to “Automatically”.
If set, only return courses that are in the given state(s). By default, “available” is returned for students and observers, and anything except “deleted”, for all other enrollment types
Term used to find users. Will search available share users with the search term in their name.
html
string
The html content to process
event
Required string
The action to take on the course.
Allowed values: delete, conclude
allow_final_grade_override
boolean
Let student final grades for a grading period or the total grades for the course be overridden
allow_student_discussion_topics
boolean
Let students create discussion topics
include[]
string
“all_courses”: Also search recently deleted courses.
“permissions”: Include permissions the current user has for the course.
“observed_users”: Include observed users in the enrollments
“course_image”: Include course image url if a course image has been set
“banner_image”: Include course banner image url if the course is a Canvas for Elementary subject and a banner image has been set
“concluded”: Optional information to include with Course. Indicates whether the course has been concluded, taking course and term dates into account.
“lti_context_id”: Include course LTI tool id.
“post_manually”: Include course post policy. If the post policy is manually post grades, the value will be true. If the post policy is automatically post grades, the value will be false.
The maximum number of teacher enrollments to show. If the course contains more teachers than this, instead of giving the teacher enrollments, the count of teachers will be given under a teacher_count key.
course[account_id]
integer
The unique ID of the account to move the course to.
course[name]
string
The name of the course. If omitted, the course will be named “Unnamed Course.”
course_ids[]
Required string
List of ids of courses to update. At most 500 courses may be updated in one call.
event
Required string
The action to take on each course. Must be one of ‘offer’, ‘conclude’, ‘delete’, or ‘undelete’.
‘offer’ makes a course visible to students. This action is also called “publish” on the web site.
‘conclude’ prevents future enrollments and makes a course read-only for all participants. The course still appears in prior-enrollment lists.
‘delete’ completely removes the course from the web site (including course menus and prior-enrollment lists). All enrollments are deleted. Course content may be physically deleted at a future date.
‘undelete’ attempts to recover a course that has been deleted. (Recovery is not guaranteed; please conclude rather than delete a course if there is any possibility the course will be used again.) The recovered course will be unpublished. Deleted enrollments will not be recovered.
Allowed values: offer, conclude, delete, undelete
assignment_ids[]
string
no description
permissions[]
string
List of permissions to check against the authenticated user. Permission names are documented in the List assignable permissions endpoint.
version_id
Required integer
The version to restore to (use the syllabus_versions include parameter in the course show API to see available versions)
source_course
string
ID or SIS-ID of the course to copy the content from
except[]
string
A list of the course content types to exclude, all areas not listed will be copied.
{
// total number of requirements from all modules
"requirement_count": 10,
// total number of requirements the user has completed from all modules
"requirement_completed_count": 1,
// url to next module item that has an unmet requirement. null if the user has
// completed the course or the current module does not require sequential
// progress
"next_requirement_url": "http://localhost/courses/1/modules/items/2",
// date the course was completed. null if the course has not been completed by
// this user
"completed_at": "2013-06-01T00:00:00-06:00"
}
{
// the unique identifier for the course
"id": 370663,
// the SIS identifier for the course, if defined. This field is only included if
// the user has permission to view SIS information.
"sis_course_id": null,
// the UUID of the course
"uuid": "WvAHhY5FINzq5IyRIJybGeiXyFkG3SqHUPb7jZY5",
// the integration identifier for the course, if defined. This field is only
// included if the user has permission to view SIS information.
"integration_id": null,
// the unique identifier for the SIS import. This field is only included if the
// user has permission to manage SIS information.
"sis_import_id": 34,
// the full name of the course. If the requesting user has set a nickname for
// the course, the nickname will be shown here.
"name": "InstructureCon 2012",
// the course code
"course_code": "INSTCON12",
// the actual course name. This field is returned only if the requesting user
// has set a nickname for the course.
"original_name": "InstructureCon-2012-01",
// the current state of the course, also known as ‘status’. The value will be
// one of the following values: 'unpublished', 'available', 'completed', or
// 'deleted'. NOTE: When fetching a singular course that has a 'deleted'
// workflow state value, an error will be returned with a message of 'The
// specified resource does not exist.'
"workflow_state": "available",
// the account associated with the course
"account_id": 81259,
// the root account associated with the course
"root_account_id": 81259,
// the enrollment term associated with the course
"enrollment_term_id": 34,
// A list of grading periods associated with the course
"grading_periods": null,
// the grading standard associated with the course
"grading_standard_id": 25,
// the grade_passback_setting set on the course
"grade_passback_setting": "nightly_sync",
// the date the course was created.
"created_at": "2012-05-01T00:00:00-06:00",
// the start date for the course, if applicable
"start_at": "2012-06-01T00:00:00-06:00",
// the end date for the course, if applicable
"end_at": "2012-09-01T00:00:00-06:00",
// the course-set locale, if applicable
"locale": "en",
// A list of enrollments linking the current user to the course. for student
// enrollments, grading information may be included if include[]=total_scores
"enrollments": null,
// optional: the total number of active and invited students in the course
"total_students": 32,
// course calendar
"calendar": null,
// the type of page that users will see when they first visit the course -
// 'feed': Recent Activity Dashboard - 'wiki': Wiki Front Page - 'modules':
// Course Modules/Sections Page - 'assignments': Course Assignments List -
// 'syllabus': Course Syllabus Page other types may be added in the future
"default_view": "feed",
// optional: user-generated HTML for the course syllabus
"syllabus_body": "<p>syllabus html goes here</p>",
// optional: the number of submissions needing grading returned only if the
// current user has grading rights and include[]=needs_grading_count
"needs_grading_count": 17,
// optional: the enrollment term object for the course returned only if
// include[]=term
"term": null,
// optional: information on progress through the course returned only if
// include[]=course_progress
"course_progress": null,
// weight final grade based on assignment group percentages
"apply_assignment_group_weights": true,
// optional: the permissions the user has for the course. returned only for a
// single course and include[]=permissions
"permissions": {"create_discussion_topic":true,"create_announcement":true},
"is_public": true,
"is_public_to_auth_users": true,
"public_syllabus": true,
"public_syllabus_to_auth": true,
// optional: the public description of the course
"public_description": "Come one, come all to InstructureCon 2012!",
"storage_quota_mb": 5,
"storage_quota_used_mb": 5,
"hide_final_grades": false,
"license": "Creative Commons",
"allow_student_assignment_edits": false,
"allow_wiki_comments": false,
"allow_student_forum_attachments": false,
"open_enrollment": true,
"self_enrollment": false,
"restrict_enrollments_to_course_dates": false,
"course_format": "online",
// optional: this will be true if this user is currently prevented from viewing
// the course because of date restriction settings
"access_restricted_by_date": false,
// The course's IANA time zone name.
"time_zone": "America/Denver",
// optional: whether the course is set as a Blueprint Course (blueprint fields
// require the Blueprint Courses feature)
"blueprint": true,
// optional: Set of restrictions applied to all locked course objects
"blueprint_restrictions": {"content":true,"points":true,"due_dates":false,"availability_dates":false},
// optional: Sets of restrictions differentiated by object type applied to
// locked course objects
"blueprint_restrictions_by_object_type": {"assignment":{"content":true,"points":true},"wiki_page":{"content":true}},
// optional: whether the course is set as a template (requires the Course
// Templates feature)
"template": true
}
{
// The URL of the calendar in ICS format
"ics": "https://canvas.instructure.com/feeds/calendars/course_abcdef.ics"
}
“public_description”: Optional information to include with each Course. When public_description is given the user-generated text for the course public description is returned.
“total_scores”: Optional information to include with each Course. When total_scores is given, any student enrollments will also include the fields ‘computed_current_score’, ‘computed_final_score’, ‘computed_current_grade’, and ‘computed_final_grade’, as well as (if the user has permission) ‘unposted_current_score’, ‘unposted_final_score’, ‘unposted_current_grade’, and ‘unposted_final_grade’ (see Enrollment documentation for more information on these fields). This argument is ignored if the course is configured to hide final grades.
“current_grading_period_scores”: Optional information to include with each Course. When current_grading_period_scores is given and total_scores is given, any student enrollments will also include the fields ‘has_grading_periods’, ‘totals_for_all_grading_periods_option’, ‘current_grading_period_title’, ‘current_grading_period_id’, current_period_computed_current_score’, ‘current_period_computed_final_score’, ‘current_period_computed_current_grade’, and ‘current_period_computed_final_grade’, as well as (if the user has permission) ‘current_period_unposted_current_score’, ‘current_period_unposted_final_score’, ‘current_period_unposted_current_grade’, and ‘current_period_unposted_final_grade’ (see Enrollment documentation for more information on these fields). In addition, when this argument is passed, the course will have a ‘has_grading_periods’ attribute on it. This argument is ignored if the total_scores argument is not included. If the course is configured to hide final grades, the following fields are not returned: ‘totals_for_all_grading_periods_option’, ‘current_period_computed_current_score’, ‘current_period_computed_final_score’, ‘current_period_computed_current_grade’, ‘current_period_computed_final_grade’, ‘current_period_unposted_current_score’, ‘current_period_unposted_final_score’, ‘current_period_unposted_current_grade’, and ‘current_period_unposted_final_grade’
“grading_periods”: Optional information to include with each Course. When grading_periods is given, a list of the grading periods associated with each course is returned.
“term”: Optional information to include with each Course. When term is given, the information for the enrollment term for each course is returned.
“account”: Optional information to include with each Course. When account is given, the account json for each course is returned.
“course_progress”: Optional information to include with each Course. When course_progress is given, each course will include a ‘course_progress’ object with the fields: ‘requirement_count’, an integer specifying the total number of requirements in the course, ‘requirement_completed_count’, an integer specifying the total number of requirements in this course that have been completed, and ‘next_requirement_url’, a string url to the next requirement item, and ‘completed_at’, the date the course was completed (null if incomplete). ‘next_requirement_url’ will be null if all requirements have been completed or the current module does not require sequential progress. “course_progress” will return an error message if the course is not module based or the user is not enrolled as a student in the course.
“sections”: Section enrollment information to include with each Course. Returns an array of hashes containing the section ID (id), section name (name), start and end dates (start_at, end_at), as well as the enrollment type (enrollment_role, e.g. ‘StudentEnrollment’).
“storage_quota_used_mb”: The amount of storage space used by the files in this course
“total_students”: Optional information to include with each Course. Returns an integer for the total amount of active and invited students.
“passback_status”: Include the grade passback_status
“favorites”: Optional information to include with each Course. Indicates if the user has marked the course as a favorite course.
“teachers”: Teacher information to include with each Course. Returns an array of hashes containing the UserDisplay information for each teacher in the course.
“observed_users”: Optional information to include with each Course. Will include data for observed users if the current user has an observer enrollment.
“tabs”: Optional information to include with each Course. Will include the list of tabs configured for each course. See the List available tabs API for more information.
“course_image”: Optional information to include with each Course. Returns course image url if a course image has been set.
“banner_image”: Optional information to include with each Course. Returns course banner image url if the course is a Canvas for Elementary subject and a banner image has been set.
“concluded”: Optional information to include with each Course. Indicates whether the course has been concluded, taking course and term dates into account.
“post_manually”: Optional information to include with each Course. Returns true if the course post policy is set to Manually post grades. Returns false if the the course post policy is set to Automatically post grades.
“locked”: Optionally include whether an enrollment is locked.
“avatar_url”: Optionally include avatar_url.
“bio”: Optionally include each user’s bio.
“test_student”: Optionally include the course’s Test Student,
if present. Default is to not include Test Student.
“custom_links”: Optionally include plugin-supplied custom links for each student,
such as analytics information
“current_grading_period_scores”: if enrollments is included as
well as this directive, the scores returned in the enrollment will be for the current grading period if there is one. A ‘grading_period_id’ value will also be included with the scores. if grading_period_id is nil there is no current grading period and the score is a total score.
‘offer’ makes a course visible to students. This action is also called “publish” on the web site.
‘conclude’ prevents future enrollments and makes a course read-only for all participants. The course still appears in prior-enrollment lists.
‘delete’ completely removes the course from the web site (including course menus and prior-enrollment lists). All enrollments are deleted. Course content may be physically deleted at a future date.
‘undelete’ attempts to recover a course that has been deleted. This action requires account administrative rights. (Recovery is not guaranteed; please conclude rather than delete a course if there is any possibility the course will be used again.) The recovered course will be unpublished. Deleted enrollments will not be recovered.
