Item Bank Endpoints

The Data API's /itembank/* endpoints allow you to create, retrieve, and maintain Item bank content programmatically.

Usage

The format of requests to Data API use the following syntax:

https://data.learnosity.com/[LTS_VERSION]/itembank/*

For example, to use the 2023.3.LTS version and the 'Get Activities' Item bank endpoint, you would create a request like so:

https://data.learnosity.com/v2023.3.LTS/itembank/activities

Note: Data API usage is subject to rate limits. Read more here: Rate Limiting With the Data API.

Retrieve Activities from your Item bank.

You would want to use this to retrieve and load your Activities into your own application, for example.

Endpoint /[LTS_VERSION]/itembank/activities
HTTP Method POST
Action Type get
Parameter Description
include
object

Properties to be returned in the response. (optional)

See below for available attributes.

include.activities
array[string]

Activity properties to be returned in the response including dt_created (date time created) and dt_updated (date time updated). (optional)

organisation_id
integer

Specifies the Item bank to retrieve Activities from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

item_pool_id
string

Specifies the Item pool from which to retrieve the Activities.

See Using Item Pools to Create Content Snapshots for more information.

item_references
object

Object with all and/or either keys.

Only Activities containing all the Items with references in all, and at least one Item from either will be returned.

Note Only for Items belonging to the same Item bank as the Activity

Note Not supported for Item pools.

limit
integer

Restricts the number of records returned.

Default: 50 records.

maxtime
integer | string

A timestamp filter based on the value provided in the sort_field parameter. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. The latest records will be returned first.

mintime
integer | string

A timestamp filter based on the value provided in the sort_field parameter. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. The latest records will be returned first.

next
string

A token used to request the next page of results.

After making an initial request, if it would produce a result set larger than the specified limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

references
array

Specifies the Activity template references to include.

Maximum: 1000 references.

sort
string

Determines response sorting.

Possible values:

  • "asc": ascending, or
  • "desc": descending.

Default: "desc"

sort_field
string

Specifies the field to sort the results by.

Possible values:

  • "created" sort by time created, or
  • "updated" sort by time updated.

Default: "created"

status
array[string]

Filter Activities by their statuses. (optional)

Possible values:

  • "published"
  • "unpublished"
  • "archived"
  • (none) - All Items are returned (all published, unpublished and archived Items)

Default: (none)

tags
array | object

Filter Activities by Tags, each array element is a TagsV2 Object or TagSearchByType object.

When searching using multiple Tags of different types, specify the advanced_tags option with the either value. See below for more information.

advanced_tags
object

Filter Activities using one of the following tagging conditions.

Possible attributes:

  • all Activities must contain all of the listed Tags
  • either Activities must contain at least one of the listed Tags
  • none Activities must not contain any of the listed Tags

At least one of the above keys must be present.

See Understanding Tag Formats for Content Creation and Filtering for more information.

Example

{
    "advanced_tags": {
        // Activities must have all of these tags...
        "all": [
            { "type": "subject", "name": "English" }
        ],

        // ...AND have at least one of these tags...
        "either": [
            { "type": "grade", "name": "6" },
            { "type": "grade", "name": "7" }
        ],

        // ...AND have none of these tags...
        "none": [
            { "type": "grade", "name": "5" },
            { "type": "grade", "name": "8" }
        ]
    },
    "include"   : {
        "activities": ["dt_created"],
    }

    // Optionally include additional generic parameters.
    ...
}

/* Example Response with Items defined as object:
{
    "meta": {
        "status":true,
        "timestamp":1389192595
    },
    "data": [
        {
            "reference":"SB_EG11Q11",
            "description":"Smarter Balanced Practice Test ELA",
            "data": {
                "activity_id": "smtest_1",
                "name": "SM Test #1",
                "rendering_type": "assess",
                "state": "initial",
                "type": "submit_practice",
                "items":
                    {
                        "reference": "SB_EG11Q11_1",
                        "id": "SB_EG11Q11_1",
                        "organisation_id": 1,
                    },
                    {
                        "reference": "SB_EG11Q11_2",
                        "id": "SB_EG11Q11_2",
                        "organisation_id": 1,
                    }
                ],
                "config": {
                    "navigation": {
                        "show_next": true,
                        "show_prev": false,
                        "show_fullscreencontrol": false,
                        "show_progress": true,
                        "show_submit": true,
                        "show_title": true,
                        "show_save": false,
                        "show_calculator": false,
                        "scroll_to_top": false,
                        "scroll_to_test": false,
                        "show_itemcount": true,
                        "toc": false,
                        "warning_on_change": true,
                        "skip_submit_confirmation": true
                    }
                }
            },
            "status": "published",
            "tags": {
                "course": [
                    "commoncore"
                ]
            },
            "dt_created": "2014-11-27 05:32:15",
            "adaptive" : {
                "difficulty": 1.2,
                "operational_exposure": null,
                "seeding_exposure": null
            }
        }
    ]
}

The Items might also be returned as an array of strings, e.g.:

"items": [
    "SB_EG11Q11_1",
    "SB_EG11Q11_2"
]
*/

Create or update Activities in your Item bank.

You would want to use this to import or bulk update Activities, or import your own Activities from another source, for example.

Endpoint /[LTS_VERSION]/itembank/activities
HTTP Method POST
Action Type set
Parameter Description
activities
array[object]

An array of objects where each represents a separate Activity.

See below for supported attributes.

Maximum: 50 entries.

activities[].base_template_id
string

Deprecated

The base template reference to be applied on the Activity.

activities[].data
object

The JSON representation of an Activity. All supported Activity properties can be found in the Items API documentation.

Default: { "rendering_type": "assess" }

activities[].data.items
array

Item definitions to be added to the Activity.

See the Items API documentation for the supported format of Items.

Note Items can be specified as either an object definition or a string reference. It is important to choose one type format and use it consistently in other parts of the config object, such as the intro_item, outro_item, and resource_item referenced under the config.navigation property.

activities[].data.config
object

The initialization options for the Activity.

See the Items API documentation for supported options.

activities[].data.sections
array

Define sections for the Activity. Sections allows you to split an Activity into separate groups of Items.

See Items API sections for more information and refer to the caveats section for important usage details.

activities[].description
string

A description for the Activity, visible only to authors via the Author API and Learnosity Author Site.

activities[].reference
string

The reference for the Activity.

Maximum: 150 ASCII characters

Note: double quotes, single quotes, and accent characters are not allowed.

activities[].status
string

Status of the Activity.

See Changing The Activity Status In The Activity Editor for more information.

Note: The Activity must be set to "published" so that it can be used in assessments.

Default: "published"

activities[].tags
object

Tags to assign to the Activity.

See TagsV2 for more information.

activities[].title
string

A human readable title used to identify an Activity which can be seen in the Author API and Learnosity Author Site.

meta
object

(optional) A metadata object which will be applied to all Activities in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Activities.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Activities.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Activities.

Maximum: 255 characters.

organisation_id
integer

Specifies the Item bank to create Activities.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Example

{
    "activities": [
        {
            "reference": "ela-unit-1",
            "data": {
                "items": [
                    "ela_item_1",
                    "ela_item_2"
                ],
                "config": {
                    "regions": "main"
                },
                "rendering_type": "assess"
            },
            "tags": {
                "demo-tagtype-1": [
                    "tag1",
                    "tag2"
                ],
                "demo-tagtype-2": [
                    "tag3"
                ]
            }
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true
    },
    "data": []
}
*/

Duplicate existing Activities, including all associated Items, Questions, and Features in your Item bank.

You would want to use this to duplicate your previous year's Activities for use in the current year, for example.

This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs endpoint and the returned job_reference to check the status of the job.

Endpoint /[LTS_VERSION]/itembank/activities/duplicate
HTTP Method POST
Action Type set
Returns A JSON object containing a job_reference that can be submitted to the jobs endpoint to track the completion of the asynchronous request.
Parameter Description
organisation_id
integer

Specifies the Item bank in which to read and duplicate Activities.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

activities
array[object]

An array of objects where each object represents an Activity to be duplicated.

Maximum: 10 Activities to be duplicated.

activities[].reference
string

Specifies the reference of an Activity you want to duplicate.

activities[].new_reference
string

(optional) Specifies the reference of the newly duplicated Activity. If this is not specified, a reference for the duplicated Activity will be automatically generated.

Note: The new Activity reference must not already exist in your Item bank.

duplicate_shared_passages
boolean

Specifies whether shared passages in Items will be duplicated. By default, shared passages are not duplicated and are referenced from the original Item instead.

Default: false

meta
object

(optional) A metadata object which will be applied to all duplicated Activities in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Activities.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Activities.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Activities.

Maximum: 255 characters.

Example

{
    "activities": [
        {
            "reference": "ACTIVITY_7",
            "new_reference": "DuplicatedActivity"
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1512120158
    },
    "data": {
        "job_reference": "69a3c789-0273-413f-bb7b-6e4f48ac5cbf" // Can be used to query the job database to find out when duplication is complete.
    }
}
*/

Overwrite Tags for Activities in your Item bank.

You would want to use this to make bulk replacements of Tags for many Activities.

Important: existing Tags assigned to Activities will be removed from the Activity and replaced with the new Tags.

Endpoint /[LTS_VERSION]/itembank/activities/tags
HTTP Method POST
Action Type set
Parameter Description
organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

activities
array

A list of Activity and Tag combinations to be processed.

Maximum: 50 Activities.

activities[].reference
string

Activity reference.

activities[].tags
object

TagsV2 object

meta
object

(optional) A metadata object which will be applied to all Activities in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the modified Activities or Tags.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or affected Activities or Tags.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the affected Activities or Tags.

Maximum: 255 characters.

Example

{
    "activities": [
        {
            "reference": "activity1",
            "tags": {
                "demo-tagtype-1": [
                    "tag1",
                    "tag2"
                ],
                "demo-tagtype-2": [
                    "tag3"
                ]
            }
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true
    },
    "data": []
}
*/

Add new Tags to Activities in your Item bank. Existing Tags assigned to these Activities will not be removed.

You would want to use this to make bulk additions of Tags to Activities.

Endpoint /[LTS_VERSION]/itembank/activities/tags
HTTP Method POST
Action Type update
Parameter Description
organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

activities
array

Array of Activity/Tag objects.

The maximum number of array elements permitted is 50.

activities[].reference
string

Activity reference

activities[].tags
object

TagsV2 object

meta
object

(optional) A metadata object which will be applied to all Activities in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the modified Activities.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the affected Activities or Tags.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the affected Activities or Tags.

Maximum: 255 characters.

Example

{
    "activities": [
        {
            "reference": "activity1",
            "tags": {
                "demo-tagtype-1": [
                    "tag4",
                    "tag5"
                ],
                "demo-tagtype-2": [
                    "tag6"
                ]
            }
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1499223766
    },
    "data": []
}
*/

Retrieves Items from the specified Item bank.

You would want to use this to use the Item data in your own application.

By default, all Items are returned (all published, unpublished and archived Items). This can be filtered by status.

Endpoint /[LTS_VERSION]/itembank/items
HTTP Method POST
Action Type get
Parameter Description
authoring_workflow
object

(optional) Include Items with a specific workflow reference and its states.

See below for supported attributes.

authoring_workflow.reference
string

Include Items by the workflow reference they belong to.

Important: the workflow reference is mandatory if the authoring_workflow is part of the request.

authoring_workflow.states
array[string]

(optional) Include Items by their workflow states.

By default, returns all Items regardless of their workflow state.

Default: ["Unassigned", all states of the workflow specified by authoring_workflow.reference]

created_by
array

Include Items with a specific user ID that created the Item.

include
object

(optional) The Item properties to be returned in the response.

See below for supported attributes.

include.items
array[string]

(optional) Item properties to be returned in the response including:

Note The authoring_workflow will be null for Items in the "Unassigned" workflow state that are returned in the response.

item_pool_id
string

Retrieves content from the specified Item pool instead of the Item bank.

limit
integer

Restricts the number of records returned.

Default: 50 records.

maxtime
int | string

A timestamp filter based on the value provided in the sort_field parameter. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. The latest records will be returned first.

mintime
int | string

A timestamp filter based on the value provided in the sort_field parameter. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. The latest records will be returned first.

next
string

A token used to request the next page of results.

After making an initial request, if it would produce a result set larger than the specified limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

questions
object

(optional) Include Items containing a specific Question reference or type.

questions.references
array[string]

Include Items that contain at least one of the specified Question references.

Maximum: 1000 Question references.

questions.types
array[string]

Include Items that contain any specified Question or Feature types, for example, mcq, clozeassociation, sharedpassage, etc.

See Question & Feature type codes for a full list.

references
array[string]

Include specific Item references in the results.

Maximum: 1000 references.

scoring_type
array

Include Items by their scoring types.

Possible values:

  • "per-question",
  • "per-dichotomous", or
  • "dependent".

See Per Question, Dichotomous, And Dependent (EBSR) Item Scoring With Examples for more information.

sort
string

Determines response sorting.

Possible values:

  • "asc": ascending, or
  • "desc": descending.

Default: "desc"

sort_field
string

Specifies the field to sort the results by. The options are as follows:

  • created: sort by time created,
  • updated: sort by time updated,
  • reference: sort by reference, or
  • title: sort by title.

Default: created

status
array

Include Items by their statuses, supports published, unpublished or archived.

Default: all Items are returned, (all published, unpublished and archived Items).

tags
array[object]

Include Items by Tags. Each element must be a TagV2 Object or TagSearchByType Object.

When searching using multiple Tags of different types, use advanced_tags with the either option (see below).

advanced_tags
object

Specify more complex search queries based on Tags, including optional or negative criteria.

At least one of the following object keys must be present:

  • all,
  • either, or
  • none.

See AdvancedTagSearchParams (Data API) for more information.

organisation_id
integer

Specifies the Item bank to retrieve Items from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Example

// Find Items by Tags
{
    "limit": 5,
    "advanced_tags": {
        // Items must have all of these Tags...
        "all": [
            {
                "type": "subject",
                "name": "English"
            }
        ],

        // ...AND have at least one of these Tags...
        "either": [
            {
                "type": "grade",
                "name": "6"
            },
            {
                "type": "grade",
                "name": "7"
            }
        ],

        // ...AND have none of these Tags...
        "none": [
            {
                "type": "grade",
                "name": "5"
            },
            {
                "type": "grade",
                "name": "8"
            }
        ]
    },
    "include": {
        "items": ["dt_created"]
    }
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1470291213,
        "next": "1445216251.1165015",
        "records": 5
    },
    "data": [
        {
            "reference": "ce76962d-d80d-4d4a-b755-20744d2fdb68",
            "title": "example title",
            "workflow": null,
            "note": null,
            "source": null,
            "definition": {
                "regions": [
                    {
                        "widgets": [
                            { "reference": "f2f1bf47-d22d-4627-8d39-c460f00c183f" }
                        ],
                        "type": "column",
                        "width": "50"
                    },
                    {
                        "widgets": [
                            { "reference": "877883fb-108e-4736-a299-3ae483d7b0e5" },
                            { "reference": "755dfab9-8687-4692-ab5d-2048a6af997f" }
                        ],
                        "type": "column",
                        "width": "50"
                    }
                ],
                "template": "dynamic"
            },
            "description": "",
            "status": "published",
            "questions": [
                {
                    "reference": "877883fb-108e-4736-a299-3ae483d7b0e5",
                    "type": "mcq"
                },
                {
                    "reference": "755dfab9-8687-4692-ab5d-2048a6af997f",
                    "type": "longtext"
                }
            ],
            "features": [
                {
                    "reference": "f2f1bf47-d22d-4627-8d39-c460f00c183f",
                    "type": "sharedpassage"
                }
            ],
            "tags": {
                "author":       ["Smarter Balanced Practice Test"],
                "course":       ["commoncore"],
                "Grade":        ["7"],
                "questiontype": ["longtext","mcq"],
                "subject":      ["English"]
            }
        },
        ...
    ]
}
*/

// Find Items by Item references
{
    "references": [
        "Grade7_ELA_1021",
        "Grade7_ELA_1022"
    ],
    "include": {
        "items": [
            "dt_created",
            "dt_updated",
            "authoring_workflow"
        ]
    }
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1470291591,
        "records": 2
    },
    "data": [
        {
            "reference": "Grade7_ELA_1021",
            "workflow": null,
            "metadata": null,
            "note": null,
            "source": null,
            "definition": {
                "regions": [
                    {
                        "widgets": [
                            { "reference": "fe359969-5170-4a57-b864-1870698f6aea" },
                            { "reference": "7550b655-74da-422f-9368-cb5a851395f2" }
                        ],
                        "type": "column",
                        "width": "50"
                    },
                    {
                        "widgets": [
                            { "reference": "a3a57364-9954-44bf-a2e4-feb1c17efdc5" }
                        ],
                        "type": "column",
                        "width": "50"
                    }
                ],
                "template": "dynamic"
            },
            "description": "",
            "status": "published",
            "questions": [
                {
                    "reference": "7550b655-74da-422f-9368-cb5a851395f2",
                    "type": "mcq"
                },
                {
                    "reference": "a3a57364-9954-44bf-a2e4-feb1c17efdc5",
                    "type": "shorttext"
                }
            ],
            "features": [
                {
                    "reference": "fe359969-5170-4a57-b864-1870698f6aea",
                    "type": "formulainput"
                }
            ],
            "tags": {},
            "dt_created": "2016-08-03 15:39:40",
            "dt_updated": "2016-08-03 15:39:47",
            "authoring_workflow": {
                "reference": "Default workflow",
                "state": "Approved"
            }
        },
        {
            "reference": "Grade7_ELA_1022",
            "workflow": null,
            "metadata": null,
            "note": null,
            "source": null,
            "definition": {
                "widgets": [
                    { "reference": "d7843b0d-da85-4686-b347-7b7c563d2abf" },
                    { "reference": "9d3dd429-0ec9-4038-a932-6ea69676619a" }
                ],
                "template": "dynamic"
            },
            "description": "",
            "status": "published",
            "questions": [
                {
                    "reference": "d7843b0d-da85-4686-b347-7b7c563d2abf",
                    "type": "mcq"
                },
                {
                    "reference": "9d3dd429-0ec9-4038-a932-6ea69676619a",
                    "type": "mcq"
                }
            ],
            "features": [],
            "tags": {},
            "dt_created": "2016-08-03 02:35:06",
            "dt_updated": "2016-08-03 02:43:14",
            "authoring_workflow": null
        }
    ]
}
*/

// Find Items including specific Question types
{
    "questions": {
        "types": [
            "imageclozetext",
            "imageclozeassociation"
        ]
    }
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1470292580,
        "next": "1441094282.886429",
        "records": 10
    },
    "data": [
        {
            "reference": "labelimage_heart_example",
            "workflow": null,
            "metadata": {
                "scoring_type": "per-question",
                "acknowledgements": null
            },
            "note": null,
            "source": null,
            "definition": {
                "widgets": [
                    { "reference": "cf35406a-88ba-4294-bca2-d013fa2bbd11" }
                ],
                "template": "dynamic"
            },
            "description": "",
            "status": "published",
            "questions": [
                {
                    "reference": "cf35406a-88ba-4294-bca2-d013fa2bbd11",
                    "type": "imageclozetext"
                }
            ],
            "features": [],
            "tags": {}
        },
        {
            "reference": "anatomy_103052b",
            "workflow": null,
            "note": null,
            "source": null,
            "definition": {
                "regions": [
                    {
                        "widgets": [
                            { "reference": "9cb5ca80-3418-4f2c-aef8-c905fff28501" }
                        ],
                        "type": "column",
                        "width": "50"
                    },
                    {
                        "widgets": [
                            { "reference": "d2f97a5a-7975-4b26-b050-8761f3443f29" },
                            { "reference": "2fb9049a-bc3e-4203-8f40-ccd5048c5807" }
                        ],
                        "type": "column",
                        "width": "50"
                    }
                ],
                "template": "dynamic"
            },
            "description": "",
            "status": "published",
            "questions": [
                {
                    "reference": "d2f97a5a-7975-4b26-b050-8761f3443f29",
                    "type": "mcq"
                },
                {
                    "reference": "2fb9049a-bc3e-4203-8f40-ccd5048c5807",
                    "type": "imageclozeassociation"
                }
            ],
            "features": [
                {
                    "reference": "9cb5ca80-3418-4f2c-aef8-c905fff28501",
                    "type": "sharedpassage"
                }
            ],
            "tags": {}
        },
        ...
    ]
}
*/

Creates or updates Items in your Item bank.

You would want to use this to import or bulk update Items, or import your own Items from another source, for example.

Endpoint /[LTS_VERSION]/itembank/items
HTTP Method POST
Action Type set
Parameter Description
items
array

An array of objects should be provided, each object representing a separate Item.

The maximum number of array elements permitted is 50.

items[].adaptive
object

(optional) The adaptive data to be used in the assessments as per Adaptive Assessments.

items[].adaptive.difficulty
integer

(optional) Set difficulty of the Item.

See Adaptive Assessments for more information.

items[].authoring_workflow
object

(optional) Object containing the Item workflow data.

See below for supported attributes.

items[].authoring_workflow.reference
string

(mandatory) Reference of the workflow the Item should use.

items[].authoring_workflow.state
string

(mandatory) Workflow state that should be assigned to the Item.

items[].definition
object

The Item layout definition.

See the Item Definition for more information.

items[].description
string

The description of the Item.

This field only appears within the Learnosity Author Site or Author API for authors.

items[].dynamic_content_data
object

Data for dynamic content Items.

See What Is Dynamic Content? for more information.

items[].features
array[string]

A list of Feature references to be included in the Item.

items[].metadata
object

The general metadata attached to the Item.

See below for supported attributes.

items[].metadata.acknowledgements
string

Provide an acknowledgement of assets owned by other organizations which are used in the assessment, for copyright purposes, such as images or other media content.

HTML values are permitted.

items[].metadata.scoring_type
string

Possible values:

  • "per-question",
  • "per-dichotomous", or
  • "dependent".

See Per Question, Dichotomous, And Dependent (EBSR) Item Scoring With Examples for more information.

items[].new_reference
string

(optional) Update an Item's reference with a new value.

When items[].reference is provided and this attribute is specified, the existing Item reference will be updated to this value.

items[].note
string

General text field for authors to leave notes which are not shown to the learner.

items[].questions
array[object]

A list of Questions to include in the Item.

See below for supported attributes.

items[].questions[].reference
string

The individual Question reference.

Must contain only letters, numbers, underscores, or dashes.

items[].reference
string

The reference for the Item.

Note: double quotes, single quotes, and accent characters are not allowed.

Maximum: 150 ASCII characters.

items[].source
string

The origins of the content for the Item, for example, the name of the book where the content is sourced from.

This field is only for authors and will not be shown to learners.

items[].status
string

The workflow status of the Item.

Possible values:

  • "published"
  • "unpublished"
  • "archived"

Note: the status must be "published" to be used in assessments.

Default: "unpublished"

items[].tags
object
TagsV2 Object
items[].title
string

A human readable title used to identify an Item which can be seen in the Author API and Learnosity Author Site.

Maximum: 150 characters.

meta
object

(optional) A metadata object which will be applied to all Items created in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

The user ID can also be passed to GET /itembank/items to filter by created_by.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Items.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Items.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Items.

Maximum: 255 characters.

organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Example

{
    "items": [
        {
            "reference": "ff685a20-12c7-42ce-a592-b046f2f07502",
            "metadata": null,
            "definition": {
                "widgets": [
                    { "reference": "88879936-952c-442a-b3c9-05e95b6ed91f" }
                ]
            },
            "status": "published",
            "questions": [
                { "reference": "88879936-952c-442a-b3c9-05e95b6ed91f" }
            ],
            "tags": {}
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1700294472
    },
    "data": []
}
*/

Duplicates Items (including all associated Questions and Features) in your Item bank.

You would want to use this to bulk duplicate many Items at once, to create the basis for a new annual assessment, for example.

Endpoint /[LTS_VERSION]/itembank/items/duplicate
HTTP Method POST
Action Type set
Parameter Description
organisation_id
integer

Specifies the Item bank in which to read and duplicate Items.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

items
array

An array of objects should be provided, each object representing an Item to be duplicated. Duplication is deep, i.e. questions are also duplicated.

The maximum number of array elements permitted is 50.

items[].reference
string

Specifies the reference of an Item you want to duplicate.

items[].new_reference
string

An optional parameter specifying the reference of the duplicated Item. new_reference should not be the reference of an already existing Item. If new_reference is not specified, a reference for the duplicated Item will be automatically generated.

duplicate_shared_passages
boolean

If set to true, shared passages will be duplicated. By default, it is false, i.e. shared passages are reused.

meta
object

(optional) A metadata object which will be applied to all Items created in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the created Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Items.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Items.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Items.

Maximum: 255 characters.

Example

{
    "items": [
        {
            "reference": "6f065658-2e19-49a5-9267-9a0d7e2b8afe",
            "new_reference": "DuplicatedItem"
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1512123317
    },
    "data": {
        "6f065658-2e19-49a5-9267-9a0d7e2b8afe": {
            "reference": "DuplicatedItem",
            "title": "Test",
            "content": "<div class="row"><div class="col-xs-12"><span class="learnosity-response question-e27e8fa1-f984-4132-b0ba-d0b6f66205bf"></span><span class="learnosity-feature feature-f86c1568-be40-4228-a21f-8fb2c5409482"></span></div></div>",
            "workflow": null,
            "metadata": null,
            "note": null,
            "source": null,
            "definition": {
                "widgets": [
                    {
                        "reference": "e27e8fa1-f984-4132-b0ba-d0b6f66205bf"
                    },
                    {
                        "reference": "f86c1568-be40-4228-a21f-8fb2c5409482"
                    }
                ],
                "template": "dynamic"
            },
            "description": "",
            "status": "published",
            "questions": [
                {
                    "reference": "e27e8fa1-f984-4132-b0ba-d0b6f66205bf",
                    "type": "clozeassociation"
                }
            ],
            "features": [
                {
                    "reference": "f86c1568-be40-4228-a21f-8fb2c5409482",
                    "type": "sharedpassage"
                }
            ],
            "tags": {
                "integration": [
                    "test"
                ]
            },
            "adaptive": {
                "difficulty": null,
                "operational_exposure": null,
                "seeding_exposure": null
            }
        }
    }
}
*/

Assign new Tags to specified Items.

You would want to use this to change the Tags on many Items at once, for example.

Important: existing Tags assigned to Items will be deleted and replaced with the new Tags.

You would want to use this to bulk assign Tags to many Items at once, for example.

Endpoint /[LTS_VERSION]/itembank/items/tags
HTTP Method POST
Action Type set
Parameter Description
items
array

Array of Item/Tag objects.

The maximum number of array elements permitted is 50.

items[].reference
string

Item reference

items[].tags
object

TagsV2 object

meta
object

(optional) A metadata object which will be applied to all Items in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

The user ID can also be passed to GET /itembank/items to filter by created_by.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the affected Items or Tags.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the affected Items or Tags.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the affected Items or Tags.

Maximum: 255 characters.

organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Example

{
    "items": [
        {
            "reference": "item1",
            "tags": {
                "demo-tagtype-1": [
                    "tag1",
                    "tag2"
                ],
                "demo-tagtype-2": [
                    "tag3"
                ]
            }
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true
    },
    "data": []
}
*/

Assign new Tags to Items.

You would want to use this to assign Tags to many Items at once, for example.

Note: Existing Tags assigned to Items will not be deleted.

Endpoint /[LTS_VERSION]/itembank/items/tags
HTTP Method POST
Action Type update
Parameter Description
items
array

Array of Item/Tag objects.

The maximum number of array elements permitted is 50.

items[].reference
string

Item reference

items[].tags
object

TagsV2 object

meta
object

(optional) A metadata object which will be applied to all Items in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the modified Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

The user ID can also be passed to GET /itembank/items to filter by created_by.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the affected Items or Tags.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the affected Items or Tags.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of affected Items or Tags.

Maximum: 255 characters.

organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Example

{
    "items": [
        {
            "reference": "item1",
            "tags": {
                "demo-tagtype-1": [
                    "tag1",
                    "tag2"
                ],
                "demo-tagtype-2": [
                    "tag3"
                ]
            }
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true
    },
    "data": []
}
*/

Retrieves Questions from your Item bank.

You would want to use this to extract existing Questions (JSON format) to perform a backup or re-use them in your application, for example.

If item_references are provided, Questions associated with the provided Item reference(s) will be returned.

Note Any Features associated with the provided references or item_references will not be returned from this endpoint. Instead, Features can be retrieved using the dedicated itembank/features endpoint.

Endpoint /[LTS_VERSION]/itembank/questions
HTTP Method POST
Action Type get
Parameter Description
include
object

(optional) Properties to be returned in the response.

See below for supported attributes.

include.questions
array[string]

(optional) Question properties to be returned in the response which can be "dt_created" and "dt_updated".

organisation_id
integer

Specifies the Item bank to retrieve Questions from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

item_pool_id
string

Return content from an Item pool instead of the Item bank

item_references
array[string]

(optional) Include Questions contained in at least one of the specified Items. Questions associated with the provided Item reference(s) will be returned.

The result will be an object with Item references as keys, and an array of associated Questions as the values.

Maximum: 1000 Item references.

Example

{
    "item_references": [
        "3ebf9a4a-0e44-4a86-971f-8fdc2d7e3957",
        "f07fecdd-e999-40aa-bd9e-9c74064fad87"
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1600921638,
        "versions": {
            "requested": "v2023.1.lts",
            "mapped": "v1.57",
            "concrete": "v1.57.3"
            "message": "INFO: Learnosity LTS version requested."
        },
        "records": 2
    },
    "data": {
        "f07fecdd-e999-40aa-bd9e-9c74064fad87": [
            {
                "type": "mcq",
                "widget_type": "response",
                "reference": "d4953353-3999-47df-b6eb-8ebce0edb3b9",
                "data": { ... },
                "metadata": {
                    "name": "Multiple choice – standard",
                    "template_reference": "9e8149bd-e4d8-4dd6-a751-1a113a4b9163"
                }
            }
        ],
        "3ebf9a4a-0e44-4a86-971f-8fdc2d7e3957": [
            {
                "type": "mcq",
                "widget_type": "response",
                "reference": "c4e65550-9224-4fd9-b6bf-153bd85d7a35",
                "data": { ... },
                "metadata": {
                    "name": "Multiple choice – multiple response",
                    "template_reference": "908de244-5c71-4c09-b094-7fb49554f2f9"
                }
            },
            {
                "type": "mcq",
                "widget_type": "response",
                "reference": "1945f9b0-24b8-4997-88dd-e0d67cf933bc",
                "data": { ... },
                "metadata": {
                    "name": "Multiple choice – standard",
                    "template_reference": "9e8149bd-e4d8-4dd6-a751-1a113a4b9163"
                }
            }
        ]
    }
}
*/
limit
integer

Restricts the number of records returned.

Default: 50 records.

maxtime
int | string

A timestamp filter based on the value provided in the sort_field parameter. The latest UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. The latest records will be returned first.

mintime
int | string

A timestamp filter based on the value provided in the sort_field parameter. The earliest UTC Unix timestamp or datetime string (in ISO 8601 format) to filter results to. The latest records will be returned first.

next
string

A token used to request the next page of results.

After making an initial request, if it would produce a result set larger than the specified limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

references
array[string]

A list of Question references.

Maximum: 1000 Question references.

sort
string

Determines response sorting.

Possible values:

  • "asc": ascending, or
  • "desc": descending.

Default: "desc"

sort_field
string

Specifies the field to sort the results by. The options are as follows:

  • created: sort by time created, or
  • updated: sort by time updated.

Default: created

types
array

Array of strings. Can be any Question/Feature/Widget type codes e.g. mcq, clozeassociation, sharedpassage, etc. See Question & Feature type codes for a full list.

Example

{
    "types": [
        "mcq"
    ],
    "include": {
        "questions": [
            "dt_created"
        ]
    }
}

/* Example Response:
{
    "meta": {
        "status":true,
        "timestamp":1389192595,
        "next": "1383057371.73016",
        "records": 100
        },
    "data": [
        {
            "type": "mcq",
            "widget_type": "response",
            "reference": "mcq_1234",
            "data": {
                "options": [
                    {
                        "label": "Hello, nice to meet you Natalie.",
                        "value": "0"
                    },
                    {
                        "label": "Yes please, I'd like some water.",
                        "value": "1"
                    },
                    {
                        "label": "Thank you, I will be there on time.",
                        "value": "2"
                    }
                ],
                "stimulus": "What is the most appropriate reply?",
                "type": "mcq",
                "validation": {
                  "scoring_type": "exactMatch",
                  "valid_response": {
                    "score": 1,
                    "value": [
                      "1"
                    ]
                  }
                },
                "ui_style": []
            },
            "dt_created": "2014-11-27 05:32:15"
        },

        ...
    ]
}
*/

Creates or overwrites Questions in your Item bank.

You would want to use this to bulk create new Questions for use in Items or import content from another source, for example.

Important: existing Questions with the same reference will be overwritten with the new properties.

Endpoint /[LTS_VERSION]/itembank/questions
HTTP Method POST
Action Type set
Parameter Description
meta
object

(optional) A metadata object which will be applied to all Questions created in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Questions, and will be shown in Learnosity Author Site when viewing the history of changes on a Question.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Questions.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Questions.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Questions.

Maximum: 255 characters.

organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

questions
array[object]

The Questions you want to set, defined as a list of objects where each represents a separate Question.

See below for supported attributes.

Maximum: 50 object definitions.

questions[].type
string

Specifies the Question type.

See Question & Feature Codes for Data API filtering for a full list of Question type codes.

questions[].reference
string

A unique reference for the Question.

Must contain only letters, numbers, underscores, or dashes.

Maximum: 150 characters.

questions[].data
object

The raw Question data (JSON).

See Question Types for a list of all possible attributes for every Question type.

Note: the HTML markup will be automatically validated and any invalid tags or attributes may be removed for security purposes. See the list of supported HTML tags.

Example

{
    "questions": [
        {
            "type": "mcq",
            "reference": "dataapi_test_001",
            "data": {
                "options": [
                    {
                        "value": "0",
                        "label": "John will have more apples and more oranges than Lucy."
                    },
                    {
                        "value": "1",
                        "label": "John will have less apples and less oranges than Lucy."
                    },
                    {
                        "value": "2",
                        "label": "John will have more apples than Lucy, but Lucy has more oranges."
                    },
                    {
                        "value": "3",
                        "label": "John will have more oranges than Lucy, but Lucy has more apples."
                    }
                ],
                "stimulus": "This is the stem",
                "type": "mcq",
                "validation": {
                    "scoring_type": "exactMatch",
                    "valid_response": [
                        {
                            "value": [
                                "0"
                            ],
                            "score": 1
                        }
                    ]
                }
            }
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1396235761
    },
    "data": []
}
*/

Duplicates Questions in your Item bank.

You would want to use this to bulk duplicate many Questions at once, to create the basis for a new annual assessment, for example.

Endpoint /[LTS_VERSION]/itembank/questions/duplicate
HTTP Method POST
Action Type set
Parameter Description
organisation_id
integer

Specifies the Item bank in which to read and duplicate the Questions.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

item_references
array

An array of Item references for which Questions should be duplicated.

duplicate_shared_passages
boolean

If set to true, shared passages will be duplicated. By default, it is false, i.e. shared passages are not duplicated.

meta
object

(optional) A metadata object which will be applied to Questions created in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the created Questions, and will be shown in Learnosity Author Site when viewing the history of changes on the Questions.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Questions.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Questions.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Questions.

Maximum: 255 characters.

Example

{
    "item_references": ["4bb30393-1fef-403b-ac5b-153bc9d1caf8"]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1512636002
    },
    "data": {
        "4bb30393-1fef-403b-ac5b-153bc9d1caf8": {
            "aa205cc7-402a-48e5-9cff-460c9f02fc24": {
                "type": "mcq",
                "widget_type": "response",
                "reference": "ef0c22cb-0d3e-4d36-ab34-26e25d65f337",
                "data": {
                    "options": [
                        {
                            "label": "[Choice A]",
                            "value": "0"
                        },
                        {
                            "label": "[Choice B]",
                            "value": "1"
                        }
                    ],
                    "stimulus": "<p>[This is the stem.]</p>",
                    "type": "mcq",
                    "validation": {
                        "scoring_type": "exactMatch",
                        "valid_response": {
                            "score": 1,
                            "value": [
                                ""
                            ]
                        }
                    },
                    "ui_style": {
                        "type": "horizontal"
                    }
                },
                "metadata": {
                    "name": "Multiple choice – standard",
                    "template_reference": "9e8149bd-e4d8-4dd6-a751-1a113a4b9163"
                }
            }
        }
    }
}
*/

Retrieves Features from your Item bank.

You would want to use this to extract existing Features (JSON format) to perform a backup or re-use them in your application, for example.

If item_references are provided, Features associated with the provided Item reference(s) will be returned.

Note Any Questions associated with the given references or item_references will not be returned from this endpoint. Questions can be retrieved using the dedicated itembank/questions endpoint.

Endpoint /[LTS_VERSION]/itembank/features
HTTP Method POST
Action Type get
Parameter Description
include
object

(optional) Properties to be returned in the response.

See below for supported attributes.

include.features
array

(optional) Feature properties to be returned in the response including "dt_created" and "dt_updated".

organisation_id
integer

Specifies the Item bank to retrieve Features from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

item_pool_id
string

Return content from an Item pool instead of the Item bank

item_references
array

Array of strings. Up to 1000 Item references may be provided. Filters the resultset to features contained in at least one of the specified Items.

limit
integer

Restricts the number of records returned.

Default: 50 records.

next
string

A token used to request the next page of results.

After making an initial request, if it would produce a result set larger than the specified limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

references
array[string]

Up to 1000 Question references may be provided.

sort
string

Determines response sorting.

Possible values:

  • "asc": ascending, or
  • "desc": descending.

Default: "desc"

sort_field
string

Specifies the field to sort the results by. The options are as follows:

  • created: sort by time created, or
  • updated: sort by time updated.

Default: created.

types
array

Array of Feature type codes, as strings eg ["audioplayer", "calculator"] See Widget codes for a full list.

Example

{
    "types": ["calculator"]
}

/* Example Response:
{
    "meta": {
        "status":true,
        "timestamp":1389192595,
        "next": "1383057371.73016",
        "records": 100
    },
    "data": [
        {
            "type": "calculator",
            "widget_type": "feature",
            "reference": "myfeature01",
            "data": {
                "type": "calculator",
                "mode": "basic"
            }
        },

        ...
    ]
}
*/

Creates or overwrites Features in your Item bank.

You would want to use this to bulk create new Features for use in Items or import content from another source, for example.

Important: existing Features with the same reference will be overwritten with the new properties.

Endpoint /[LTS_VERSION]/itembank/features
HTTP Method POST
Action Type set
Parameter Description
features
array

An array of objects should be provided, each object representing a separate Feature.

The maximum number of array elements permitted is 50.

features[].type
string

Feature type code, see Widget codes for a full list.

features[].reference
string

A unique reference for the Feature, must contain only letters, numbers, underscore or dash. Maximum length 150 characters.

features[].data
object

Feature type object data

Invalid HTML markup might be removed.

meta
object

(optional) A metadata object which will be applied to all Features created in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Features, and will be shown in Learnosity Author Site when viewing the history of changes on the Features.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Features.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Features.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Features.

Maximum: 255 characters.

organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Example

{
    "features": [
        {
            "type": "calculator",
            "reference": "myfeature01",
            "data": {
                "mode": "basic",
                "type": "calculator"
            }
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1396235761
    },
    "data": []
}
*/

Duplicates Features in your Item bank.

You would want to use this to bulk duplicate many Features at once, to create the basis for a new annual assessment, for example.

Endpoint /[LTS_VERSION]/itembank/features/duplicate
HTTP Method POST
Action Type set
Parameter Description
organisation_id
integer

Specifies the Item bank in which to read and duplicate the Features.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

item_references
array

An array of Item references for which Features should be duplicated.

duplicate_shared_passages
boolean

If set to true, shared passages will be duplicated. By default, it is false, i.e. shared passages are not duplicated.

meta
object

(optional) A metadata object which will be applied to all Features created in this request.

See below for supported attributes.

meta.user
object

(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Features, and will be shown in Learnosity Author Site when viewing the history of changes on the Features.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Features.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Features.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Features.

Maximum: 255 characters.

Example

{
    "item_references": ["4bb30393-1fef-403b-ac5b-153bc9d1caf8"]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1512636002
    },
    "data": {
        "4bb30393-1fef-403b-ac5b-153bc9d1caf8": {
            "aa205cc7-402a-48e5-9cff-460c9f02fc24": {
                "type": "mcq",
                "widget_type": "response",
                "reference": "ef0c22cb-0d3e-4d36-ab34-26e25d65f337",
                "data": {
                    "options": [
                        {
                            "label": "[Choice A]",
                            "value": "0"
                        },
                        {
                            "label": "[Choice B]",
                            "value": "1"
                        }
                    ],
                    "stimulus": "<p>[This is the stem.]</p>",
                    "type": "mcq",
                    "validation": {
                        "scoring_type": "exactMatch",
                        "valid_response": {
                            "score": 1,
                            "value": [
                                ""
                            ]
                        }
                    },
                    "ui_style": {
                        "type": "horizontal"
                    }
                },
                "metadata": {
                    "name": "Multiple choice – standard",
                    "template_reference": "9e8149bd-e4d8-4dd6-a751-1a113a4b9163"
                }
            }
        }
    }
}
*/

Retrieve Tags from your Item bank.

You would want to use this to retrieve specific Tags for use in your own application, for example.

Endpoint /[LTS_VERSION]/itembank/tagging/tags
HTTP Method POST
Action Type get
Parameter Description
organisation_id
integer

Specifies the Item bank to retrieve Tags.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

item_pool_id
string

Returns content from an Item pool instead of the Item bank

limit
integer

Restricts the number of records returned.

Default: 50 records.

names
array[string]

A list of Tag names to retrieve.

next
string

A token used to request the next page of results.

After making an initial request, if it would produce a result set larger than the specified limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

sort
string

Determines response sorting.

Possible values:

  • "asc": ascending, or
  • "desc": descending.

Default: "desc"

sort_field
string

Specifies the field to sort the results by.

Possible values:

  • "sort_key": sort by Tag type and then by the manual Tag name order (sort_key) defined in Author Site and then by Tag name.
  • "created": sort by time created.
  • "updated": sort by time updated.

Default: updated.

types
array[string]

A list of Tag types to retrieve.

Note: Tag types returned unless the sort_field is "sort_key", in which case at least one types must be provided.

Example

{
    "types": [
        "course",
        "subject"
    ],
    "names": [
        "Math",
        "Advanced Math",
        "English"
    ],
    "sort_field": "updated",
    "limit": 2
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1389193100,
        "records": 2,
        "next": "138919500.781"
    },
    "data": [
        {
            "type": "course",
            "name": "Math",
            "description": "Elementary math"
        },
        {
            "type": "course",
            "name": "English",
            "description": "English reading, writing, literature"
        }
    ]
}
*/

Creates or overwrites Tags in your Item bank.

You would want to use this to bulk create new Tags to assign to Items and Activities.

Important: existing Tags with the same type and name will be overwritten with the new values.

Endpoint /[LTS_VERSION]/itembank/tagging/tags
HTTP Method POST
Action Type set
Parameter Description
meta
object

(optional) A metadata object which will be applied to all Tags created in this request.

See below for supported attributes.

meta.user
object

(optional) Object. Contains user details of the user issuing the create or update operation in this request. The user details are recorded in the audit trail for each of the new or modified Tags.

Default: Manual User/Data GUI

meta.user.id
string

(mandatory) ID of the user issuing this request.

Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.

Note: The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

Maximum: 50 characters.

meta.user.firstname
string

(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created or updated Tags.

Maximum: 50 characters.

meta.user.lastname
string

(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created or updated Tags.

Maximum: 50 characters.

meta.user.email
string

(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created or updated Tags.

Maximum: 255 characters.

organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

tags
array[object]

An array of TagV2 objects should be provided, each object representing a separate Tag type or Tag combination.

Maximum: 1000 TagV2 objects.

tags[].description
string

A longer description for the Tag.

This may be provided as null which will unset the value. When this is omitted, the description field will remain unchanged.

tags[].name
string

(mandatory) The Tag name.

tags[].sort_key
integer

The Tag order set up in the Author Site.

tags[].type
string

(mandatory) The Tag type.

Example

{
    "tags": [
        {
            "type": "course",
            "name": "Common Core",
            "sort_key": 1,
            "description": "common core subjects"
        },
        {
            "type": "subject",
            "name": "Maths",
            "sort_key": 3,
            "description": "mathematics"
        },
        {
            "type": "subject",
            "name": "English",
            "sort_key": 2,
            "description": "English literature and comprehension"
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1396235761
    },
    "data": []
}
*/

Retreives the hierarchy of Tag types for the specified hierarchy references.

You would want to use this to retrieve specific Tag hierarchies for use in your own application, for example.

Note: each returned Tag type represents one level of the hierarchy. Each Tag within a level is considered as a "node".

See How Do Tag Hierarchies Work? for more information.

Endpoint /[LTS_VERSION]/itembank/tagging/hierarchies
HTTP Method POST
Action Type get
Parameter Description
organisation_id
integer

Specifies the Item bank to retrieve the Tag Hierarchies from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

references
array[string]

A list of hierarchy references to retrieve.

Example

{
  "references": [ "TagHierarchyTest" ],
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1490241998,
        "records": 1
    },
    "data": [
        {
            "reference": "TagHierarchyTest",
            "tag_types": [
                {
                    "name": "author",
                    "description": null
                },
                {
                    "name": "subject",
                    "description": null
                },
                {
                    "name": "course",
                    "description": null
                },
                {
                    "name": "questiontype",
                    "description": null
                }
            ]
        }
    ]
}
*/

Retrieves the next node in a Tag hierarchy from your Item bank.

You would want to use this to retrieve specific Tag hierarchy nodes for use in your own application, for example.

See How Do Tag Hierarchies Work? for more information.

Endpoint /[LTS_VERSION]/itembank/tagging/hierarchies/nodes
HTTP Method POST
Action Type get
Parameter Description
organisation_id
integer

Specifies the Item bank to retrieve the Tag hierarchy nodes from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

path
array[TagsV2]

An ordered array of TagV2 objects.

reference
string

The reference of the Tag hierarchy to get nodes for.

Example

{
  "reference": "TagHierarchyTest",
  "path": [
      { "type": "author",   "name": "J.D. Salinger" },
      { "type": "subject",  "name": "English" }
  ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1482285520,
        "records": 2
    },
    "data": [
        {
            "type": "course",
            "name": "commoncore",
            "description": "Common Core"
        },
        {
            "type": "course",
            "name": "example course",
        }
    [
}
*/

Retrieve a list of Item pools for the specified Item bank.

You would want to use this to see all available Item pools for your Item bank and retrieve content from the desired Item pool.

See Using Item Pools to Create Content Snapshots for more information.

Endpoint /[LTS_VERSION]/itembank/pools
HTTP Method POST
Action Type get
Parameter Description
organisation_id
integer

Specifies the Item bank to retrieve Item pools from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

limit
integer

Restricts the number of records returned.

Default: 50 records.

next
string

A token used to request the next page of results.

After making an initial request, if it would produce a result set larger than the specified limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

references
array[string]

A list of Item pool references to retrieve.

sort
string

Determines response sorting.

Possible values:

  • "asc": ascending, or
  • "desc": descending.

Default: "desc"

sort_field
string

Specifies the field to sort the results by. The options are as follows:

  • created: sort by time created, or
  • updated: sort by time updated.

Default: created.

status
array[string]

Include Item pools by their statuses.

Possible values:

  • "published",
  • "unpublished",
  • "pending", or
  • "halted".

Default: all statuses.

Example

{
    "references": ["ela-district-a"]
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1389193100,
    "records": 1
  },
  "data": {
    "reference": "ela-district-a",
    "description": "Content pool for ELA District A",
    "name": "ELA 2015 District A",
    "status": "published",
    "dt_created": 2015-01-08T07:34:00Z,
    "dt_updated": 2015-01-08T07:34:00Z
  }
}
*/

Create new Item pools for the specified Item bank.

You would want to use this to create a new Item pool based on specific Items, Activities, or Items and Activities that have specific Tags.

See Using Item Pools to Create Content Snapshots for more information.

This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs endpoint and the returned job_reference to check the status of the job.

Endpoint /[LTS_VERSION]/itembank/pools
HTTP Method POST
Action Type set
Returns JSON object containing a job_reference that can be used against the jobs endpoint to track the completion of the (asynchronous) request.
Parameter Description
organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

pools
array[object]

A list of Item pools to create.

See below for supported attributes.

Maximum: 50 Item pool definitions.

pools[].reference
string

The unique Item pool reference.

pools[].name
string

A human readable name used to identify the Item pool.

pools[].content
object

Configuration for Items and/or Activities to add to the Item pool. Content has to contain at least one valid entry.

See below for supported attributes.

pools[].content.item_references
array[string]

Item references to add to the pool.

pools[].content.activity_references
array[string]

Activity references to add to the pool.

pools[].content.tags
array[TagV2|object]

Include Items and Activities which have been assigned to specific Tags or Tag combinations to be added into the Item pool.

See Understanding Tag Formats for Content Creation and Filtering for more information.

There are two modes of operation for specifying Tags:

  • Simple: a list of TagsV2 objects.
  • Advanced: each entry can consist of an array of filtering options for required_tags and additional_tags. See below attributes for more information.
pools[].content.tags[].required_tags
array[TagV2]

(mandatory) A list of TagsV2 objects, in which content must be tagged with all Tags in the array.

pools[].content.tags[].additional_tags
array[TagV2]

(optional) A list of TagsV2 objects, in which content must be tagged with at least one Tag in the array.

pools[].content.item_tags
array
The same as tags, but only Items will be added using this Tag list.
pools[].content.activity_tags
array

The same as tags, but only Activities will be added using this Tag list.

Note Items associated with the Activity will be added as normal.

pools[].status
string

Possible values:

  • "published"
  • "unpublished"

Default: "published"

pools[].overwrite
boolean

(optional) Overwrite the Item pool if the Item pool reference already exists.

Default: false

pools[].ignore_empty_additional_tags
boolean

(optional) When using advanced Tag combinations, if no content is found using the additional_tags, then required_tags will be ignored.

Set this option to true to ignore cases where no content is tagged using additional_tags (for example, the Tag combination is treated as if the optional additional_tags array had not been set).

pools[].set_unpublished_to_published
boolean

(optional) Set all content to published when added to the Item pool.

By default, unpublished content cannot be added to Item pools. You can use this to include content regardless of its publishing status.

Default: false

pools[].description
string

(optional) A description of the Item pool.

Example

{
  "pools": [
    {
      "reference": "new_test_pool",
      "name": "New test pool",
      "description": "This is a test pool",
      "content": {
        "item_references": [
            "dataapi_test_001"
        ],
        "activity_references": [
          "CCASWinter14G06AVE"
        ],
        "tags": [
          {
            "type": "course",
            "name" : "commoncore"
          }
        ]
      }
    }
  ]
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1389178000,
    "records": 1
  },
  "data": [
    {
        "pool_reference": "new_test_pool",
        "job_reference": "987y12nflkdv"
    }
  ]
}
*/

/*
 * Advanced Tag combination example.
 *
 * The below Tag combinations example will add:
 *   1) any content tagged with all tagnames of tagtype "course"
 *   2) any content tagged with:
 *        (foo: bar AND baz: *) AND (qux: quux OR corge: * OR grault: garply)
 */
{
  "pools": [
    {
      "reference": "new_test_pool",
      "name": "New test pool",
      "description": "This is a test pool",
      "content": {
        "tags": [
          {
            "type": "course"
            // Tag name is optional
          },
          {
            "required_tags": [
              {
                "type": "foo",
                "name": "bar"
              },
              {
                "type": "baz"
                // Tag name is also optional in advanced Tag usage
              }
            ],
            "additional_tags": [
              {
                "type": "qux",
                "name": "quux"
              },
              {
                "type": "corge"
              },
              {
                "type": "grault",
                "name": "garply"
              }
            ]
          }
        ]
      }
    }
  ]
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1389193100,
    "records": 1
  },
  "data": [
    {
      "pool_reference": "new_test_pool",
      "job_reference": "54fcffa26610"
    }
  ]
}
*/

Update existing Item pools to add or overwrite content.

You would want to use this to make amendments or corrections to existing Item pools.

Note Items pools are designed to be a snapshot of an Item bank. For large changes, it is highly recommended to create a new Item pool instead of modifying an existing Item pool. This reduces the risk of making unintended changes to live assessments.

See Using Item Pools to Create Content Snapshots for more information.

This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs endpoint and the returned job_reference to check the status of the job.

Endpoint /[LTS_VERSION]/itembank/pools
HTTP Method POST
Action Type update
Returns JSON object containing a job_reference that can be used against the jobs endpoint to track the completion of the (asynchronous) request.
Parameter Description
organisation_id
integer

Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

pools
array

An array of objects should be provided, each object representing a separate Item pool.

The maximum number of array elements permitted is 50.

pools[].reference
string
Unique id of the new pool
pools[].name
string
User-friendly name of the pool
pools[].content
object
Information about which Items/Activities to add to the pool. Content has to contain at least one valid entry.
pools[].content.item_references
array
Item references to add to the pool
pools[].content.activity_references
array
Activity references to add to the pool
pools[].content.tags
array
Simple: Each Tag entry consists of a Tag type and a Tag name - Tag types are mandatory , while Tag names are optional .

Advanced: Each Tag entry can consist of an array of required_tags and an array of additional_tags - required_tags are mandatory, additional_tags are optional.
required_tags is an array of tags (as described in simple), in which content must be tagged with every Tag in the array.
additional_tags is an array of tags (as described in simple), in which content must be tagged with at least one Tag in the array.


Items and Activities tagged with those Tags (or adhere to the Tag combinations) are added to the pool.

See also the knowledgebase article about Tags.
pools[].content.item_tags
array
The same as 'Tags', but only Items will be added using this Tag list.
pools[].content.activity_tags
array

The same as 'Tags', but only Activities will be added using this Tag list.

Note Items associated with the Activity will be added as normal.

pools[].status
string
[optional] Either published or unpublished , defaults to published
pools[].set_unpublished_to_published
boolean
[optional] Set to true to allow the update of a pool with unpublished content.
By default, you are prevented from storing unpublished content in Item bank pools.
Default: false.
pools[].overwrite
boolean
[optional] If true, only the existing pool objects listed in pools[].content will be overwritten with the new state of these objects in Item bank.
Default: false.

Example

{
  "pools": [
    {
      "reference": "new_test_pool",
      "name": "Updated test pool",
      "description": "This is a test pool",
      "content": {
        "item_references": [
          "dataapi_test_001"
        ],
        "activity_references": [
          "CCASWinter14G06AVE"
        ],
        "tags": [
          {
            "type": "course",
            "name" : "commoncore"
          }
        ]
      }
    }
  ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1440467404
    },
    "data": [
        {
            "pool_reference": "new_test_pool",
            "job_reference": "8f49db43-0d54-4fc5-8154-a721b0334898"
        }
    ]
}
*/

Upload assets directly to Learnosity cloud storage in bulk.

This endpoint generates a set of pre-signed upload URLs (one per asset requested), which can then be used to upload the asset files themselves. The upload is done by sending an HTTP PUT request to each of the signed URLs. See the section Uploading Asset Files using Signed URLs for more information.

The endpoint also returns the corresponding public URLs for retrieving the uploaded assets later on.

The endpoint infers the Content-Type for assets based on the filename extension (e.g. image/jpeg for .jpg, image/png for .png). There is support for overriding the inferred type, or specifying it for files where it cannot be inferred from the filename extension.

Endpoint /[LTS_VERSION]/itembank/upload/assets
HTTP Method POST
Action Type get
Parameter Description
items
array

Array of objects

subkeys
array

An array of strings, where each string is a "key" representing the desired name for a particular asset. This key is used in the path of the asset's public URL.

subkeys forbids using certain character combinations that may have special meaning in the context of HTTP URLs or filenames. The following are not allowed:

  • leading or trailing forward slash (/)
  • backslash (\)
  • path elements that are either . or ..
  • consecutive slashes (//)
  • empty string

subkey_types
object

(optional) An object with string keys and string values, where each object key corresponds to an entry in the subkeys list and each value is a Content-Type.

subkey_types can be used to indicate the required Content-Type for subkeys which:

  • have no filename extension, or
  • have a filename extension that is not in Learnosity's default mapping
  • have a required Content-Type that does not match Learnosity's default mapping

Every key in the subkey_types object must correspond exactly to an element of the subkeys array.

A key may be omitted if the default Content-Type for a file's extension is what is desired.

organisation_id
integer

Specifies the Item bank for uploading assets.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Response

An array of objects, with each object representing one of the assets to be uploaded. Each object contains the following keys:

  • upload - the upload URL to which to make a PUT request for one of the given assets. Once generated, this URL is accessible for a limited time after which it expires. See Uploading Asset Files using Signed URLs for more detail.
  • public - the final publicly accessible URL for one of the given assets. This URL is usable as soon as the file upload is completed.
  • content_type - the specified or inferred content type for this resource. This value must be included as the Content-Type header in the PUT request to the upload URL.

After retrieving signed upload URLs from this endpoint, files can be uploaded by sending PUT requests to those URLs. This can be performed using a simple Curl call, or the HTTP client of your choice. For example, the following command will upload a sample JPEG file called content1.jpg from a Curl-enabled terminal to a pre-signed URL:

$ curl --request PUT \
    --header "Expect: 100-continue" \
    --header "Content-Type: image/jpeg" \
    --data-binary "@content1.jpg" \
    "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/path/to/content1.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=uULtl3Yqh1UVxX6RxhCDVprxqqg%3D&x-amz-acl=public-read"

When making the PUT request:

  • Set the Content-Type header to the appropriate content_type value provided by the endpoint for this subkey.
  • Set the Expect: 100-continue header if your HTTP client supports it, to avoid transmitting unnecessary data in certain error cases. See the Expect-continue handshake optimisation introduced in HTTP 1.1.

The signed upload URLs expire a short duration (currently 60 minutes) after they're issued. If one or more signed URLs have expired, call this endpoint again to obtain new upload URLs.

Since this operation is a PUT, if a signed URL is generated for an existing asset key, uploading to it will overwrite any existing content.

The request will fail if the Content-Type header is omitted, or if it not set to the exact value provided in the response from the endpoint for the corresponding subkey.

Example

{
    "organisation_id": 1,
    "subkeys": [
        "path/to/content1.jpg",
        "path/to/content2.jpg",
        "other/content3.jpg",
        "other/legacy_content"
    ],
    "subkey_types": {
        "other/legacy_content": "image/png"
    }
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1485320066,
        "records": 3
    },
    "data": [{
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/path/to/content1.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=uULtl3Yqh1UVxX6RxhCDVprxqqg%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/path/to/content1.jpg",
            "content_type": "image/jpeg"
        },
        {
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/path/to/content2.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=IrUFv0HqVSX7c0KiiQmBTuPMjds%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/path/to/content2.jpg",
            "content_type": "image/jpeg"
        },
        {
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/other/content3.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=X%2BfVesr8am%2FTcmlBnyT3RpWOigY%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/other/content3.jpg",
            "content_type": "image/jpeg"
        },
        {
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/other/legacy_content?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=X%2BfVesr8am%2FTcmlBnyT3RpWOigY%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/other/legacy_content",
            "content_type": "image/png"
        }
    ]
}
*/

Download all content in assessment from your Item bank for offline use in a local device. The content from this endpoint is used in the Learnosity local device assessment app.

Note: This is an enterprise product. Contact Learnosity Support for more information.

This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs endpoint and the returned job_reference to check the status of the job.

Endpoint /[LTS_VERSION]/itembank/offlinepackage
HTTP Method POST
Action Type get
Returns

JSON object containing a job_reference that can be used against the jobs endpoint to track the completion of the (asynchronous) request.

The jobs endpoint (with job_reference) will include a download URI to the local device assessment content package.

Parameter Description
organisation_id
integer

Specifies the Item bank to retrieve content from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

activity_references
array[string]

A list of Activity references to include in the local device package.

Default: 1000 Activity references.

items
array[object]

A list of ItemObjects to be packaged.

item_references
array[string]

Deprecated

A list of Item references to be packaged.

Maximum: 1000 references.

base_directory
string

(optional) Specify the base directory for all content and assets.

Default: "/vendor/itembank"

Example

{
    "items": [
        {
            "id": "item_reference_1",
            "reference": "item_reference_1"
        },
        {
            "id": "item_reference_2",
            "reference": "item_reference_2",
            "organisation_id": 1
        }
    ],
    "activity_references": [
        "activity_reference_1"
    ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1389193100,
        "records": 1
    },
    "data": [
        {
            "job_reference": "69fe1753-dec5-43d3-9b83-e2b87e1d8ffa"
        }
    ]
}
*/

Retrieve all of the Item review workflows available for the specified Item bank.

You would want to use this to inspect the all of the rules applied to a specific workflow.

Endpoint /[LTS_VERSION]/itembank/workflows
HTTP Method POST
Action Type get
Parameter Description
organisation_id
integer

(optional) Specifies the Item bank to retrieve workflows from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

limit
integer

(optional) Restricts the number of records returned.

Default: 50 records.

next
string

(optional) A token used to request the next page of results.

After making an initial request, if it would produce a result set larger than the specified limit, the return packet will include a token in meta.next. Pass the token provided by meta.next along with the original request parameters to retrieve the next page of results.

references
array

(optional) Include specific workflow references.

Maximum: 1000 workflow references.

Example

{
    "request": {
        "references": [
            "Default workflow"
        ]
    }
}

/* Example Response
{
    "meta": {
        "status": true,
        "timestamp": 1583988357,
        "records": 1
    },
    "data": [
        {
            "reference": "Default workflow",
            "initial_state_reference": "DRAFT",
            "final_state_reference": "APPROVED",
            "description": "Default workflow description",
            "workflow_states": [
                {
                    "reference": "APPROVED",
                    "description": "APPROVED STATE",
                    "label": "APPROVED",
                    "workflow_transitions": [
                        {
                            "label": "APPROVED TO REVIEW",
                            "to_state_label": "REVIEW",
                            "to_state_reference": "REVIEW",
                            "display_order": 1
                        }
                    ]
                },
                {
                    "reference": "BLOCKED",
                    "description": "BLOCKED STATE",
                    "label": "BLOCKED",
                    "workflow_transitions": [
                        {
                            "label": "BLOCKED TO REVIEW",
                            "to_state_label": "REVIEW",
                            "to_state_reference": "REVIEW",
                            "display_order": 1
                        },
                        {
                            "label": "BLOCKED TO REWORK",
                            "to_state_label": "REWORK",
                            "to_state_reference": "REWORK",
                            "display_order": 2
                        },
                        {
                            "label": "BLOCKED TO DRAFT",
                            "to_state_label": "DRAFT",
                            "to_state_reference": "DRAFT",
                            "display_order": 3
                        }
                    ]
                },
                {
                    "reference": "DRAFT",
                    "description": "DRAFT STATE",
                    "label": "Draft",
                    "workflow_transitions": [
                        {
                            "label": "DRAFT TO REVIEW",
                            "to_state_label": "REVIEW",
                            "to_state_reference": "REVIEW",
                            "display_order": 1
                        },
                        {
                            "label": "DRAFT TO BLOCKED",
                            "to_state_label": "BLOCKED",
                            "to_state_reference": "BLOCKED",
                            "display_order": 2
                        }
                    ]
                },
                {
                    "reference": "REVIEW",
                    "description": "REVIEW STATE",
                    "label": "REVIEW",
                    "workflow_transitions": [
                        {
                            "label": "REVIEW TO APPROVED",
                            "to_state_label": "APPROVED",
                            "to_state_reference": "APPROVED",
                            "display_order": 1
                        },
                        {
                            "label": "REVIEW TO REWORK",
                            "to_state_label": "REWORK",
                            "to_state_reference": "REWORK",
                            "display_order": 2
                        }
                    ]
                },
                {
                    "reference": "REWORK",
                    "description": "REWORK STATE",
                    "label": "REWORK",
                    "workflow_transitions": [
                        {
                            "label": "REWORK TO REVIEW",
                            "to_state_label": "REVIEW",
                            "to_state_reference": "REVIEW",
                            "display_order": 1
                        },
                        {
                            "label": "REWORK TO BLOCKED",
                            "to_state_label": "BLOCKED",
                            "to_state_reference": "BLOCKED",
                            "display_order": 2
                        }
                    ]
                }
            ]
        }
    ]
}
*/

Create a new Item review workflow for the specified Item bank.

You would want to use this to set up a new Item review workflow so that your content creators can collaborate as desired.

Endpoint /[LTS_VERSION]/itembank/workflows
HTTP Method POST
Action Type set
Parameter Description
organisation_id
integer

(optional) Specifies the Item bank to update.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

workflows
array[object]

(mandatory) A list of the workflows to create.

Maximum: 50 workflows.

See below for supported attributes.

workflows[].reference
string

(mandatory) The unique reference for the workflow.

Once created, this workflow reference can be used in the Author API initialization options to enable the workflow states.

Maximum: 150 ASCII characters.

Note: double quotes, single quotes, and accent characters are not allowed.

workflows[].description
string

(optional) The description of the workflow.

Maximum: 1000 characters.

workflows[].initial_state_reference
string

(mandatory) The starting state of the workflow.

This reference must match one of the state references provided in workflows[].workflow_states[].

Maximum: 150 characters.

Note: The reference is case sensitive.

workflows[].final_state_reference
string

(mandatory) The ending state of the workflow.

This reference must match one of the state references provided in workflows[].workflow_states[].

Maximum: 150 characters.

Note: The reference is case sensitive.

workflows[].workflow_states
array[object]

(mandatory) A list of each separate state for the workflow.

See below for supported attributes.

workflows[].workflow_states[].reference
string

(mandatory) The unique reference for the state.

Maximum: 150 characters.

Note: The reference is case sensitive.

workflows[].workflow_states[].description
string

(optional) The description of the state.

Maximum: 1000 characters.

workflows[].workflow_states[].label
string

(mandatory) A human readable label for the state shown in the user interface.

Maximum: 150 characters.

workflows[].workflow_states[].
workflow_transitions
array[object]

(mandatory) Define all the states for the workflow.

See below for supported attributes to define each state.

workflows[].workflow_states[].
workflow_transitions[].to_state_reference
string

(mandatory) The next state reference that the current state can progress to.

This reference must match one of the state references provided in workflows[].workflow_states[].

Maximum: 150 characters.

Note: The reference is case sensitive.

workflows[].workflow_states[].
workflow_transitions[].display_order
integer

(mandatory) Set the display order for this state.

The state transitions are numerically sorted in the user interface, from smallest to largest, where the smallest appears on top. For example, when you have five states numbered from one to five, one will appear first in the list of states.

Example

{
    "request": {
        "workflows": [
            {
                "reference": "Default workflow",
                "initial_state_reference": "DRAFT",
                "final_state_reference": "APPROVED",
                "description": "Default workflow description TEST1",
                "workflow_states": [
                    {
                        "reference": "DRAFT",
                        "description": "DRAFT STATE",
                        "label": "DRAFT",
                        "workflow_transitions": [
                            {
                                "to_state_reference": "REVIEW",
                                "display_order": 1
                            },
                            {
                                "to_state_reference": "BLOCKED",
                                "display_order": 2
                            }
                        ]
                    },
                    {
                        "reference": "BLOCKED",
                        "description": "BLOCKED STATE",
                        "label": "BLOCKED",
                        "workflow_transitions": [
                            {
                                "to_state_reference": "REVIEW",
                                "display_order": 1
                            },
                            {
                                "to_state_reference": "REWORK",
                                "display_order": 2
                            },
                            {
                                "to_state_reference": "DRAFT",
                                "display_order": 3
                            }
                        ]
                    },
                    {
                        "reference": "REWORK",
                        "description": "REWORK STATE",
                        "label": "REWORK",
                        "workflow_transitions": [
                            {
                                "to_state_reference": "REVIEW",
                                "display_order": 1
                            },
                            {
                                "to_state_reference": "BLOCKED",
                                "display_order": 2
                            }
                        ]
                    },
                    {
                        "reference": "REVIEW",
                        "description": "REVIEW STATE",
                        "label": "REVIEW",
                        "workflow_transitions": [
                            {
                                "to_state_reference": "APPROVED",
                                "display_order": 1
                            },
                            {
                                "to_state_reference": "REWORK",
                                "display_order": 2
                            }
                        ]
                    },
                    {
                        "reference": "APPROVED",
                        "description": "APPROVED STATE",
                        "label": "APPROVED",
                        "workflow_transitions": [
                            {
                                "to_state_reference": "REVIEW",
                                "display_order": 1
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1583990495
    },
    "data": []
}
*/

Retrieve all Activity assessment player templates for a specific Item bank.

You would want to use this to retrieve all assessment player templates to review the layout, settings, and label bundles which have been configured.

Endpoint /[LTS_VERSION]/itembank/playertemplates
HTTP Method POST
Action Type get
Parameter Description
organisation_id
integer

(optional) Specifies the Item bank to retrieve Activity player templates from.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Example

// No parameters applicable. The endpoint always returns all Activity player templates.
{}

/* Example Response:
{
"meta": {
    "status": true,
    "timestamp": 1633504859,
    "records": 1
},
"data": [
    {
        "name": "Test Player Template",
        "reference": "980fe27e-b0e4-4b18-bb32-f036921ca1ea",
        "json": {
            "regions": {
                "top-left": [
                    {
                        "type": "title_element"
                    },
                    {
                        "type": "save_button"
                    }
                ],
                "top-right": [
                    {
                        "type": "pause_button",
                        "position": "right"
                    },
                    {
                        "type": "timer_element"
                    },
                    {
                        "type": "reading_timer_element"
                    },
                    {
                        "type": "itemcount_element"
                    }
                ],
                "right": [
                    {
                        "type": "verticaltoc_element"
                    },
                    {
                        "type": "fullscreen_button"
                    },
                    {
                        "type": "reviewscreen_button"
                    },
                    {
                        "type": "resource_button"
                    },
                    {
                        "type": "accessibility_button"
                    },
                    {
                        "type": "calculator_button"
                    },
                    {
                        "type": "flagitem_button"
                    },
                    {
                        "type": "notepad_button"
                    },
                    {
                        "type": "stickynote_add_button"
                    },
                    {
                        "type": "stickynote_visibility_button"
                    },
                    {
                        "type": "drawing_mode_button"
                    },
                    {
                        "type": "drawing_visibility_button"
                    }
                ],
                "bottom-right": [
                    {
                        "type": "next_button"
                    },
                    {
                        "type": "previous_button"
                    }
                ],
                "items": [
                    {
                        "type": "slider_element",
                        "scrollable_option": false
                    }
                ]
            },
            "labelBundle": {
                "actionsave": "Commit"
            },
            "custom_data": {
                "custom_key": "some_value"
            }
        }
    }
]
}
*/

This has been superseded by get /itembank/tagging/tags.

Endpoint /[LTS_VERSION]/itembank/tags
HTTP Method POST
Action Type get
Parameter Description
organisation_id
v2019.2.LTS or later
integer

Returns content from the Item bank with the supplied ID.

The consumer making the request will need to have access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console.

item_pool_id
string

Returns content from an Item pool instead of the Item bank

tags
array

Array of Tag strings

types
array

Array of Tag type strings

Example

{
    "types": ["course", "subject"],
    "tags": ["English", "Maths"],
}

/* Example Response:
{
  "meta": {
    "status": true,
    "timestamp": 1389193100
  },
  "data": {
    "subject": [
      "English",
      "Maths"
    ]
  }
}
*/

This has been superseded by set /itembank/tagging/tags.

Endpoint /[LTS_VERSION]/itembank/tags
HTTP Method POST
Action Type set
Parameter Description
organisation_id
v2019.2.LTS or later
integer

Sets content to the Item bank with the supplied ID.

The consumer making the request will need to have access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console.

tags
object
TagsV2 object

The maximum number of distinct Tag types permitted in the TagsV2 object is 1000.

Example

{
    "tags": {
        "course": [
            "Common Core"
        ],
        "subject": [
            "maths",
            "english"
        ]
    }
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1396235761
    },
    "data": []
}
*/

Activity Base Templates have been deprecated in favor of Player Templates - migrate and use get /itembank/playertemplates instead for LTS versions higher than v2022.1.LTS. See migration guide for more information.

No parameters (bar Organisation ID) applicable. The endpoint always returns all Activity base templates.

Endpoint /[LTS_VERSION]/itembank/activities/templates
HTTP Method POST
Action Type get
Parameter Description
organisation_id
v2019.2.LTS or later
integer

Returns content from the Item bank with the supplied ID.

The consumer making the request will need to have access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console.

Example

// No parameters applicable. The endpoint always returns all Activity templates.
        {}

        /* Example Response:
                {
                    "meta": {
                        "status": true,
                        "timestamp": 1408491907,
                        "records": 3
                    },
                    "data": [
                        {
                            "reference": "BASETEMPLATE_1",
                            "data": {
                                "config": {
                                    "ui_style": "main",
                                    "navigation": {
                                        "show_title": true,
                                        "show_itemcount": true,
                                        "show_fullscreencontrol": false,
                                        "toc": true,
                                        "auto_save": {
                                            "save_interval_duration": 300
                                        }
                                    }
                                }
                            },
                            "description": "base_1",
                            "status": "archived"
                        },
                        {
                            "reference": "BASETEMPLATE_2",
                            "data": {
                                "config": {
                                    "ui_style": "main",
                                    "navigation": {
                                        "show_title": true,
                                        "toc": true
                                    },
                                    "title": "base_2 title",
                                    "subtitle": "base_2 subtitle"
                                }
                            },
                            "description": "base_2",
                            "status": "published"
                        },
                        {
                            "reference": "BASETEMPLATE_3",
                            "data": {
                                "config": {
                                    "ui_style": "horizontal",
                                    "navigation": {
                                        "show_title": false,
                                        "toc": false
                                    },
                                    "title": "base_3 title",
                                    "subtitle": "base_3 subtitle"
                                }
                            },
                            "description": "base_3",
                            "status": "published"
                        }
                    ]
                }
                */