Items API Initialization

This article details the properties that are passed as parameters to the window.LearnosityItems.init() method to initialize Items API.

This method is the starting point to initializing and rendering Items API, and as you can see in the example below, takes two key parameters:

The Initialization object is mandatory. Further details on getting started and initializing Items API can also be found in the Getting Started guide.

var initializationObject = {
    "security": {
        "consumer_key": "INSERT_CONSUMER_KEY_HERE",
        "domain": "",
        "timestamp": "20120202-1234",
        "signature": "SHA256-HASH - See Security"
    "request": {
        "activity_id": "math.c2.u7",
        "name": "Math Chapter 2 – Unit 7",
        "rendering_type": "assess",
        "type": "submit_practice",
        "session_id": "0adc8ac1-d71f-494e-860b-378c2d75a926",
        "user_id": "aeee19fb-4e7b-435c-92f9-d93a1099988b",
        "items": [
        "config": {
            "title": "Math Chapter 2 – Unit 7",
            "subtitle": "Multiplication",
            "regions": "main",
            "navigation": {
                "show_intro": true,
                "show_outro": true,
                "skip_submit_confirmation": false,
                "warning_on_change": false,
                "auto_save": {
                    "save_interval_duration": 500
            "annotations": true,
            "time": {
                "max_time": 1500,
                "limit_type": "soft",
                "warning_time": 120
            "configuration": {
                "shuffle_items": false,
                "idle_timeout": {
                    "interval": 300,
                    "countdown_time": 60

var callbacks = {
    errorListener: function (e) {
        // Adds a listener to all error codes.
        console.log("Error Code ", e.code);
        console.log("Error Message ", e.msg);
        console.log("Error Detail ", e.detail);

    readyListener: function () {
        console.log("Learnosity Items API is ready");

var itemsApp = window.LearnosityItems.init(initializationObject, callbacks);

Initialization Object

The Initialization object is a JSON object which is passed as the first parameter into the window.LearnosityItems.init() method. It includes all the information needed to initialize the API.

It contains the following two top-level properties:

The Security object is a property generated by the Learnosity serverside SDKs to ensure that any of the APIs are only initialized from a secured, allowed source, using your consumer key and secret.

This is handled by our SDKs in:

For other languages, please see our Security & Authentication page on how to sign your requests.

The Request object contains all of the configuration properties for user & session identification, user interface look and feel, as well as which Items or Activities to load.

Only a few properties are mandatory, the rest provide a high level of customization to enable you to tailor the assessment experience to suit your needs.


= mandatory property



The ID of the Activity that will be used in Learnosity's Reports API and Data API to group all unique user sessions together. Should not exceed 36 characters. Recommended to be a UUID.

Use a value that represents different end users attempting the same "test" blueprint, as you can then request reports for all sessions that share the same activity_id.

Note Can be ommited for non-Adaptive activities with type: "local_practice".



The reference of an existing Activity stored in Learnosity's Item bank. This Activity acts as a template which has a default set of properties for the Activity, without needing to define the same properties each time the same Activity is created. Some of these properties can then be overridden if required, by providing them in this request object.

E.g. a "base" Activity may use a custom regions configuration that should be applied to all Assessments, and further overrides can be made such as changing the selected Items, changing the title of the assessment, etc.

Activity references (called activity_template_id when you initialize an assessment) are limited to 150 characters.

See Activity definition for more information.



Configuration for an adaptive assessment. Learnosity offers several forms including; Item Adaptive Testing, Item Branching and Testlet Adaptive.

Important Only supported with rendering_type: "assess" and supersedes items

To configure this option, see the complete list of all Initialization Options for Adaptive Assessments.



The properties inside this object are used to configure options relating to the user experience and behavior of Items API.



The properties inside this object are used to configure options relating to Dynamic Content, a form of smart content which allows many variations of the same Question.

See What is Dynamic Content? for more information.

"dynamic_items": {
    "data_table_seed": "SOME_SEED",
    "try_again": {
        "max_attempts": 5,
        "random": true


Enables the use of Events API.

Important Your Learnosity consumer must have Events API enabled for this option to take effect. See Events API for more information.

Default: false



Sets the default Item Pool to retrieve content (Activity template and Items) from.

See Data API Pools for more information.


array[string |ItemObject]

Sets the content to be shown in the session. Can be an array of unique string Item references, or an array of Item objects for advanced usage.

Important This is a mandatory property unless adaptive or sections are configured, or using an activity_template_id with items in it.

Note The items property has priority over activity_template_id, if they are passed simultaneously.

Note The items and sections can not be used at the same time in a request object.



Name of the activity that will be displayed in Learnosity's Reports API and Data API.

Important Required only if submitting responses to Learnosity.



Sets the default Item Bank to retrieve content (Activity template and Items) from.

See Multiple Activity template and Item sources for more information.



The rendering type dictates whether the activity will be rendered using the Learnosity's assessment player, or Items embedded in multiple different locations.
Possible values:
  • "assess"
  • "inline"


Brings the Item tags along with the assessment content. Used for content debugging in test environments or other advanced use-cases.

Default: false



Override the scoring type of the items loaded from the Item Bank (unless otherwise overridden per item, which takes precedence).

See Item Scoring tutorial for more information.



Sections allow split a single activity into discrete buckets of items, with the ability to have different title and subtitle per section.

Important Once students progress to a new section, they cannot navigate back (unless allow_backward_navigation is enabled).

Note The sections and items can not be used at the same time in a request object.



This ID is used to uniquely identify the users assessment session.

Important Must be a valid UUID Version 4. e.g: f47ac10b-58cc-4372-a567-0e02b2c3d479



Custom metadata to include for the user's assessment session. This metadata is stored when the session is saved or submitted.



Sets the state of the activity. State controls the startup modes of the API, to allow for different behaviors during an assessment. For example, the initial state is applied when students first access the assessment, and a new session is created. Similarly, resume state is used when a student is coming back to an assessment, but they have accessed it before, so we resume the same session that they started earlier. You can also specify the preview state, which allows learners to view Learnosity Items without being able to answer questions or submit the assessment. For more detail, see the Help article on this topic.

In the submit_practice session type, Items API always checks if the session exists to decide if the state should be initial or resume and adjusts it accordingly. This means you only really need to set the state when you want to initialize with either the review or preview states.

Possible values:
  • "initial"
  • "resume"
  • "review"
  • "preview"

Default: "initial"

See Switching Between Testing and Reviewing With States for more information.



Subscores are a breakdown of a total score achieved for an activity. They allow you to extract groups of Items, and focus on scoring them separately.

See Activity Subscores for more information.



Defines the session context, including whether student responses are to be submitted and stored or remain available locally only.
Possible values:
  • "local_practice" - assessment is rendered, but the responses will not be stored in Learnosity's servers
  • "submit_practice" - assessment is rendered and responses are stored in Learnosity's servers, allowing for grading and review of the session
  • "feedback" - the assessment is aimed at capturing teacher's feedback. More information

Default: "submit_practice"



The ID of the user that is attempting the assessment. Should not exceed 50 characters, nor contain any personally identifiable information. Recommended to be a UUID.

The Callbacks object contains optional callback functions that allow detection of the ready status of an Items API instance and any errors encountered.

An example of how to construct this object can be seen above.

The readyListener callback in particular is very important for the correct functioning of Items API. Most of the methods provided by the returned object from window.LearnosityItems.init() will not be fully available until after the readyListener callback has triggered.




This function is called when the user attempts to close the browser window. You would use this to display a custom error notification or dialog in order to warn the user that they may lose their progress if they don't save.



Function to be called on a Learnosity error event. Receives an Error object.

See troubleshooting for more information.



Function to be called when the API has been successfully initialized.