Introduction

The Knewton API exposes constructs designed to support a variety of learning applications spanning a range of educational use cases. To integrate with Knewton, the application designer must understand the features that the Knewton API provides, identify the subset of features their application must rely upon, and connect the application’s logic to corresponding API endpoints.

This page outlines the key abstractions and organizing principles of the Knewton API, contextualizing the other pages of this Implementation Guide, which offer more in-depth coverage of the API features.

Data Model

The primary purpose of the Knewton API is to provide learning applications with useful analytics and recommendations to power adaptive learning experiences and provide actionable insights to students and instructors. Before these benefits can be realized, the Knewton Platform must first be made aware of the learning application’s users and seeded with information about the pedagocial intent and learning objectives of any adaptive assignments that students will be asked to complete, about the interactions of students with content items, and about the content itself.

To that end, a partner application must create and manage the following types of entities defined by the Knewton Platform data model.

Knowledge Graph: A graph data structure that describes the relationships between each individual deliverable question or instructional item and the concepts that those items assess or instruct, as well as the prerequisite relationships between those concepts. Creation of an accurate and well-designed knowledge graph is a critical part of integration with the Knewton Platform, and is generally undertaken by a partner’s content developers in cooperation with your Knewton representative. The Knowledge Graph is ingested to the Knewton Platform through a separate offline workflow rather than through an API. See Adaptive Content for more information.
Account: Represents an end-user’s relationship with the partner learning application. See Managing User Accounts for more detail.
Learning Instance: Represents a group of students working on a common set of assignments. See Managing Learning Instances for more detail.
Registration: Represents an account’s membership in a Learning Instance, and defines the user’s role in that learning instance: either an instructor or a student. See Managing Learning Instances for more detail.
Goal: Expresses the target learning objectives, scope, completion criteria, deadlines, and desired pedagogy for an adaptive learning experience assigned to the students registered to a particular learning instance. See Building Goals for more detail.
Student Event: Represents the outcome and duration of a student’s interaction with a particular instructional or assessing content item. If the interaction occurs in the context of a Knewton adaptive assignment, the event will also reference the associated Goal. See Sending Events for more detail.

The relationships between these entities are shown in the figure below. Data Model

Provisioning Flow

The entities described in the Knewton Platform’s Data Model must be sent to the Knewton Platform, via offline processes in some cases and via the Knewton API in other cases, before meaningful recommendations or analytics can be retrieved.

The figure below shows the dependencies between the provisioning operations for the different types of entities. Provisioning Flow

Each learning application integrated with the Knewton API will have a unique partner client ID and secret, which will be used to authenticate subsequent requests to the API. These credentials will be provided by your Knewton representative.
The content developers for the learning application must work with your Knewton representative to author a content inventory and knowledge graph spreadsheet, which must be validated and ingested into the Knewton Platform before Learning Instances may be created.

The partner admin credentials should be exchanged via the OAuth APIs for an oauth token, which should be used to authenticate all subsequent requests to Knewton APIs. See Authentication and Users for more detail.
Accounts for your instructors and students are managed through the Accounts APIs.
Learning Instances are managed through the Learning Instances APIs.
Student and instructor Accounts are associated with Learning Instances through Registrations, which are managed through the Registrations APIs.
Goals for the Learning Instances are managed through the Goals APIs.
Goals can be auto-assigned to all of the students registered in a Learning Instance upon their creation, or these assignments can be manually managed through the Goals APIs.
Student events for any static assignments (non-adaptive assignments that do not have a corresponding Knewton Goal) can be submitted for any Registration via the Events APIs.
Student events for adaptive assignments can be submitted for Goals that have been assigned to the student’s Registration via the Events APIs.

All of these provisioning operations are typically performed on an ongoing basis as new users, courses/learning contexts, enrollments, assignments, and student interactions are recorded by the learning application, or as previously created entities are updated.

Storing Knewton Platform Entity IDs

The Knewton Platform creates UUID identifiers for any resources created through the Knewton API. In many cases this ID will need to be included in subsequent API requests that reference previously created entities.

For example, the request payload to create a Registration resource must contain the Knewton-provided UUIDs for the Account and the Learning Instance that the Registration associates. To register a user with a corresponding Knewton Account ID 3de63120-ebcd-4568-935a-0d04e3bf0f72 into a course with a corresponding Knewton Learning Instance ID 41409a38-3153-41f8-aa90-d6bacb7e23ed, the learning application would create a resource under /registrations:

POST /v0/registrations
{
    "account_id": "3de63120-ebcd-4568-935a-0d04e3bf0f72",
    "learning_instance_id": "41409a38-3153-41f8-aa90-d6bacb7e23ed",
    "type": "learner"
}

The Knewton Platform creates the registration, assigns it its own ID, and returns that ID in the response.

{
    "id": "83ce46e1-ae1e-493a-95ab-826ee02a4118",
    "account_id": "3de63120-ebcd-4568-935a-0d04e3bf0f72",
    "learning_instance_id": "41409a38-3153-41f8-aa90-d6bacb7e23ed",
    "type": "learner"
}

Whenever a Knewton API response includes the ID of a created resource, the learning application is expected to store that ID and associate it with whatever entity in the learning application’s data model corresponds to the created Knewton Platform resource so that it can be looked up and used as needed in subsequent requests.

Knewton IDs to Store

Account ID: returned when creating an Account with POST /v0/accounts.
Learning Instance ID: returned when creating a Learning Instance with POST /v0/learning-instances/.
Registration ID: returned when registering an Account into a Learning Instance with POST /v0/registrations/.
Goal ID: returned when creating a Goal with POST /v0/learning-instances/{li_id}/scoped-goals.
Recommendation ID: returned when requesting a Recommendation with GET /v0/registrations/{registration-id}/recommendation. (Note that this is a slightly different case, in that the Recommendation resource is created automatically by the Knewton Platform and mererly retrieved by the learning application.)

Recommendations and Analytics

Now the fun part! Once the learning application has implemented the required provisioning flows, the Knewton Platform will start to build up an understanding of students’ mastery of the different concepts defined in the Knowledge Graph, and the learning application can retrieve recommendations and analytics. See the following sections of this implementation guide for more ideas about how to use these capabilities to build awesome features that your users will love!

Getting Started
Working with Adaptive Assignments
Predictive Learner Analytics
- Predicted Score
General API Usage
Brand Guidelines
Glossary