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.1.LTS version and the 'Get Activities' Item bank endpoint, you would create a request like so:

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

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

If you have created an Activity with Author API version 1.37 or higher, the Items added to the Activity are specified as objects. Activities created with older versions of Author API identify Items with their reference only. So when retrieving Activities with this endpoint, be aware that Items can be in both formats (see the example response for details).

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

(optional) Properties to be returned in the response.
include.activities
array

(optional) Activity properties to be returned in the response including dt_created and dt_updated.
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
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, not supported for Item pools.
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the value provided in sort_field parameter. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from. This returns the latest records first.
mintime
int | string

A timestamp filter based on the value provided in sort_field parameter. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to. This returns the latest records first.
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
references
array

Filter by specific Activity template references. Up to 1000 references may be provided.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
sort_field
string

Determines sort field, can be created to sort by time created or updated to sort by time updated

Default: created
status
array

Filter Activities by their statuses, supports published, unpublished or archived

Default: published, unpublished
tags
array | object

Filter Activities by tags, each array element is a TagV2 Object or TagSearchByType object, which must contain a type, and an optional name properties.

When searching using multiple tags of different types please use advanced_tags with the either option.
advanced_tags
object

At least one of the all/either/none object keys must be present.

See the knowledge base article for more details.

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"
]
*/
Endpoint /itembank/activities
HTTP Method POST
Action Type set
Parameter Description
activities
array

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

The maximum number of array elements permitted is 50.
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.

A default value is set if the property passed is null or an empty object.

Default: { "rendering_type": "assess" }
activities[].data.items
array

See Items API documentation for the supported format of Items.

Note Items in this array can be specified as either an object definition or a string reference. It is important to keep the Items' type consistent when referred to in other parts of the config object, such as the intro_item, outro_item and resource_item Items referenced under the config.navigation property.
activities[].data.config
object

Object holding the config properties for the Activity. See Items API documentation for supported options.
activities[].data.sections
array

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

Note Do not use sections if activities[].data.items is used. Items defined here should be consistent with those defined in other parts of the config object, too, as mentioned in the activities[].data.items note.
activities[].description
string

A string used to describe the Activity template, visible only to authors via the Author API.
activities[].reference
string

Maximum of 150 characters and must only contain ASCII printable characters, except for double quotes, single quotes and accent.
activities[].status
string

Status of the Activity, it must be published to be called by the Items API.

Default: published
activities[].tags
object

Tags to apply to the Activity, the key is the Tag type and the value is an array of Tag names (strings). If the Tag type or Tag name doesn't exist, it will be created.
activities[].title
string		 A friendly label used to identify Activity templates when browsing within Author API.
meta
object

(optional) Object containing request-level metadata applying to all Activities in this request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the new/modified Activities, and will be displayed in Author Site when viewing the history of changes on an Activity.

If not provided, the default 'Manual User/Data GUI' user is recorded against the new/modified Activities.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the new/modified Activities.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the new/modified Activities.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the new/modified Activities.
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.

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":[]
}
*/
Endpoint /itembank/activities/duplicate
HTTP Method POST
Action Type set
Parameter Description
organisation_id
v2019.2.LTS or later
integer

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

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

An array of objects should be provided, each object representing an Activity to be duplicated. Duplication is deep, i.e. Items and Questions are also duplicated.

The maximum number of array elements permitted is 10.
activities[].reference
string

Specifies the reference of an Activity you want to duplicate.
activities[].new_reference
string

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

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

(optional) Object containing request-level metadata applying to the duplication request.
meta.user
object

(optional) Object. Contains user details of the user issuing the duplicate operation in this request. The user details are recorded in the audit trail as the user who created the new Activities, and will be displayed in Author Site when viewing the history of changes on those Activities.

If not provided, the default 'Manual User/Data GUI' user is recorded against the created Activities.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the duplicate operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the duplicate operation in this request. This first name is recorded in the audit trail for each of the created Activities.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the duplicate operation in this request. This last name is recorded in the audit trail for each of the created Activities.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the duplicate operation in this request. This email address is recorded in the audit trail for each of the created Activities.

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.
    }
}
*/
Endpoint /itembank/activities/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.
activities
array

Array of Activity/Tag objects.

The maximum number of array elements permitted is 50.
activities[].reference
string

Activity reference
activities[].tags
object

TagsV0 object
meta
object

(optional) Object containing request-level metadata applying to all Activities in this request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the affected Activities/Tags, and will be displayed in Author Site when viewing the history of changes on an Activity.

If not provided, the default 'Manual User/Data GUI' user is recorded against the affected Activities/Tags.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the affected Activities/Tags.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the affected Activities/Tags.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the affected Activities/Tags.

Example

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

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

Assign new Tags to existing Activities. Existing Tags assigned to these Activities will not be deleted.

Endpoint /itembank/activities/tags
HTTP Method POST
Action Type update
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.
activities
array

Array of Activity/Tag objects.

The maximum number of array elements permitted is 50.
activities[].reference
string

Activity reference
activities[].tags
object

TagsV0 object
meta
object

(optional) Object containing request-level metadata applying to all Activities in this request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the affected Activities/Tags, and will be displayed in Author Site when viewing the history of changes on an Activity.

If not provided, the default 'Manual User/Data GUI' user is recorded against the affected Activities/Tags.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the affected Activities/Tags.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the affected Activities/Tags.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the affected Activities/Tags.

Example

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

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

Returns a list of Items. By default, all Items are returned, (all published, unpublished and archived Items). This can be filtered by using the status parameter.

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

(optional) Allows to filter Items by workflow reference and its states.

Version added: v2020.3.LTS
authoring_workflow.reference
string

(mandatory) Filters Items by the workflow reference they belong to.

Version added: v2020.3.LTS
authoring_workflow.states
array

(optional) Filters Items by their workflow states.

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

Version added: v2020.3.LTS
created_by
array

Filters Items by the users (the id) who created them, either by the Author API or the Data API.
include
object

(optional) Properties to be returned in the response.
include.items
array

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

Note authoring_workflow is null for Items in "Unassigned" state that are returned in the response.
item_pool_id
string

Returns content from an Item pool instead of the Item bank
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the value provided in sort_field parameter. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from. This returns the latest records first.
mintime
int | string

A timestamp filter based on the value provided in sort_field parameter. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to. This returns the latest records first.
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
questions
object

(optional) Search Items by Question reference or type.
questions.references
array

Up to 1000 Question references may be provided. Filters the resultset to Items containing at least one of the specified Question objects.
questions.types
array

Filter by Items containing any Question/Feature/Widget type codes, in an array, as strings e.g. mcq, clozeassociation, sharedpassage, etc. See Question & Feature type codes for a full list.
references
array

Filter by specific Item references. Up to 1000 references may be provided.
scoring_type
array

Filter Items by their scoring types, can include per-question, dichotomous or dependent.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
sort_field
string

Determines sort field, can be created to sort by time created or updated to sort by time updated or reference to sort by reference or title to sort by title

Default: created
status
array

Filter Items by their statuses, supports published, unpublished or archived

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

Filter Items by Tags, each array element is a TagV2 Object or TagSearchByType Object, which must contain a type, and an optional name properties.

When searching using multiple Tags of different types please use advanced_tags with the either option.
advanced_tags
object

At least one of the all/either/none object keys must be present.

See the knowledge base article for more details.
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

{
    "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"]
            }
        },
        ...
    ]
}
*/

{
    "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
        }
    ]
}
*/

{
    "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": {}
        },
        ...
    ]
}
*/
Endpoint /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[].authoring_workflow
object

(optional) Object containing the Item workflow data.

Version added: v2020.3.LTS
items[].authoring_workflow.reference
string

(mandatory) Reference of the workflow the Item should belong to.

Version added: v2020.3.LTS
items[].authoring_workflow.state
string

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

Version added: v2020.3.LTS
items[].definition
object		 Object containing the Item layout definition. See the Item Definition section for full details.
items[].description
string		 Used only within the Learnosity Author Site.
items[].dynamic_content_data
object		 Data for dynamic content Items. See Dynamic Content tutorial for more information.
items[].features
array		 Array of Feature references attached to this Item.
items[].metadata
object

Object containing hidden Item metadata.
items[].metadata.acknowledgements
string

Any attributions necessary for shared work used on the Item (eg images). HTML values are permitted.
items[].metadata.scoring_type
string

Support values are per-question, dichotomous and dependent
items[].new_reference
string

(optional) Allows to rename an Item.

If provided in Item data i of the items array, Item i.reference will be renamed to i.new_reference, and its content updated with the rest of the data included in i.
items[].note
string		 Used only within the Learnosity Author Site.
items[].questions
array		 Array of Question objects containing string references
items[].questions[].reference
string		 Must contain only letters, numbers, underscore or dash.
items[].reference
string		 Maximum of 150 characters. Must only contain ASCII printable characters, except for double quotes, single quotes and accent.
items[].source
string		 Used only within the Learnosity Author Site
items[].status
array

Status of the Item, supports published, unpublished or archived.

Note status must be published to be used by the Items API.

Default: unpublished
items[].tags
object		 TagsV0 Object
items[].title
string		 Used only within Author API and the Learnosity Author Site
meta
object

(optional) Object containing request-level metadata applying to all Items in this request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the new/modified Items, and will be displayed in Author Site when viewing the history of changes on an Item.

If not provided, the default 'Manual User/Data GUI' user is recorded against the new/modified Items.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.

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

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the new/modified Items.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the new/modified Items.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the new/modified Items.
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.

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": 1470294472
    },
    "data": []
}
*/
Endpoint /itembank/items/duplicate
HTTP Method POST
Action Type set
Parameter Description
organisation_id
v2019.2.LTS or later
integer

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

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.
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) Object containing request-level metadata applying to the duplication request.
meta.user
object

(optional) Object. Contains user details of the user issuing the duplicate operation in this request. The user details are recorded in the audit trail as the user who created the new Items, and will be displayed in Author Site when viewing the history of changes on those Items.

If not provided, the default 'Manual User/Data GUI' user is recorded against the created Items.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the duplicate operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the duplicate operation in this request. This first name is recorded in the audit trail for each of the created Items.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the duplicate operation in this request. This last name is recorded in the audit trail for each of the created Items.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the duplicate operation in this request. This email address is recorded in the audit trail for each of the created Items.

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
            }
        }
    }
}
*/

Set Items' Tags. Existing Tags assigned to Items will be deleted and replaced with the new Tags.

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

TagsV0 object
meta
object

(optional) Object containing request-level metadata applying to all Items/Tags in the request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the affected Items/Tags, and will be displayed in Author Site when viewing the history of changes on an Item.

If not provided, the default 'Manual User/Data GUI' user is recorded against the affected Items/Tags.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.

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

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the affected Items/Tags.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the affected Items/Tags.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the affected Items/Tags.
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.

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. Existing Tags assigned to Items will not be deleted.

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

TagsV0 object
meta
object

(optional) Object containing request-level metadata applying to all Items/Tags in the request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the affected Items/Tags, and will be displayed in Author Site when viewing the history of changes on an Item.

If not provided, the default 'Manual User/Data GUI' user is recorded against the affected Items/Tags.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.

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

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the affected Items/Tags.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the affected Items/Tags.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the affected Items/Tags.
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.

Example

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

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

This endpoint returns Question widgets from the Learnosity Item bank.

If item_references are passed, Questions associated with the given Item reference/s will be returned.

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

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

(optional) Properties to be returned in the response.
include.questions
array

(optional) Question properties to be returned in the response including dt_created and dt_updated
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

Return content from an Item pool instead of the Item bank
item_references
array

(optional) Array of strings. Up to 1000 Item references may be provided. Filters the resultset to Questions contained in at least one of the specified items.

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

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, with a maximum of 50.

Default: 50
maxtime
int | string

A timestamp filter based on the value provided in sort_field parameter. Highest UTC unix timestamp or datetime string (in ISO 8601) to get results from. This returns the latest records first.
mintime
int | string

A timestamp filter based on the value provided in sort_field parameter. Lowest UTC unix timestamp or datetime string (in ISO 8601) to filter results to. This returns the latest records first.
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
references
array

Array of strings. Up to 1000 Question references may be provided.
sort
string

Determine sorting order, can be desc or asc

Default: desc
sort_field
string

Determines the sort field. Can be created to sort by time created or updated to 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"
        },

        ...
    ]
}
*/
Endpoint /itembank/questions
HTTP Method POST
Action Type set
Parameter Description
meta
object

(optional) Object containing request-level metadata applying to all Questions in the request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the new/modified Question, and will be displayed in Author Site's audit trail view for Items containing the Question.

If not provided, the default 'Manual User/Data GUI' user is recorded against the new/modified Questions.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the new/modified Questions.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the new/modified Questions.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the new/modified Questions.
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.
questions
array

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

The maximum number of array elements permitted is 50.
questions[].type
string

Question type code, see Widget codes for a full list.
questions[].reference
string

A unique reference for the Question, must contain only letters, numbers, underscore or dash. Maximum length 150 characters.
questions[].data
object

Question type object data

Invalid HTML markup might be removed.

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": []
}
*/
Endpoint /itembank/questions/duplicate
HTTP Method POST
Action Type set
Parameter Description
organisation_id
v2019.2.LTS or later
integer

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

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_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) Object containing request-level metadata applying to the duplication request.
meta.user
object

(optional) Object. Contains user details of the user issuing the duplicate operation in this request. The user details are recorded in the audit trail as the user who created the new Questions, and will be displayed in Author Site when viewing the history of changes on those Questions.

If not provided, the default 'Manual User/Data GUI' user is recorded against the created Questions.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the duplicate operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the duplicate operation in this request. This first name is recorded in the audit trail for each of the created Questions.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the duplicate operation in this request. This last name is recorded in the audit trail for each of the created Questions.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the duplicate operation in this request. This email address is recorded in the audit trail for each of the created Questions.

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"
                }
            }
        }
    }
}
*/

This endpoint returns Feature widgets from the Learnosity Item bank.

If item_references is passed, features associated with the given Item reference/s will be returned.

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

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

(optional) Properties to be returned in the response.
include.features
array

(optional) Feature properties to be returned in the response including dt_created and dt_updated
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

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, with a maximum of 50.

Default: 50
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
references
array

Array of strings. Up to 1000 Question references may be provided.
sort
string

Determine sorting order, can be desc or asc

Default: desc
sort_field
string

Determines the sort field, can be created to sort by time created or updated to 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"
            }
        },

        ...
    ]
}
*/
Endpoint /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) Object containing request-level metadata applying to all Features in the request.
meta.user
object

(optional) Object. Contains user details of the user issuing the create/update operation in this request. The user details are recorded in the audit trail for each of the new/modified Features, and will be displayed in Author Site's audit trail view for Items containing the Feature.

If not provided, the default 'Manual User/Data GUI' user is recorded against the new/modified Features.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request. This value is displayed in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request. This first name is recorded in the audit trail for each of the new/modified Features.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request. This last name is recorded in the audit trail for each of the new/modified Features.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request. This email address is recorded in the audit trail for each of the new/modified Features.
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.

Example

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

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1396235761
    },
    "data": []
}
*/
Endpoint /itembank/features/duplicate
HTTP Method POST
Action Type set
Parameter Description
organisation_id
v2019.2.LTS or later
integer

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

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_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) Object containing request-level metadata applying to the duplication request.
meta.user
object

(optional) Object. Contains user details of the user issuing the duplicate operation in this request. The user details are recorded in the audit trail as the user who created the new Items, and will be displayed in Author Site when viewing the history of changes on those Items.

If not provided, the default 'Manual User/Data GUI' user is recorded against the created Features.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the duplicate operation in this request. This value is displayed in the Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the duplicate operation in this request. This first name is recorded in the audit trail for each of the created Features.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the duplicate operation in this request. This last name is recorded in the audit trail for each of the created Features.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the duplicate operation in this request. This email address is recorded in the audit trail for each of the created Features.

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"
                }
            }
        }
    }
}
*/
Endpoint /itembank/tagging/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
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
names
array

Array of strings constraining the Tag names returned.
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
sort_field
string

Determines sort field, can be:

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

Default: updated
types
array

Array of strings constraining the 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"
        }
    ]
}
*/

Update Tag attributes, creating new Tags if necessary.

This endpoint can be used to update the case of existing Tag types and names and to create new Tags. When the Tag specifications (type and name) are accompanied by any optional attributes (sort_key, description) those attributes will also be updated.

The type and name are mandatory. While case is not significant in Tag and Tag type lookups, the case of strings used in the endpoint is preserved allowing that case to be updated.

The sort_key or description may be omitted, in which case these attributes will not be changed. The description may also be provided as null in which case the description will be unset. this is different from omitting the description which will leave the field unchanged.

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

(optional) Object containing request-level metadata applying to all Tags in the request.
meta.user
object

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

If not provided, the default 'Manual User/Data GUI' user is recorded against the new/modified Tags.
meta.user.id
string

(mandatory) Maximum of 50 characters.

ID of the user issuing the create/update operation in this request.

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.
meta.user.firstname
string

(optional) Maximum of 50 characters.

First name of the user issuing the create/update operation in this request.
meta.user.lastname
string

(optional) Maximum of 50 characters.

Last name of the user issuing the create/update operation in this request.
meta.user.email
string

(optional) Maximum of 255 characters.

Email address of the user issuing the create/update operation in this request.
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
array

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

The maximum number of TagV2 elements permitted is 1000.
tags[].description
string

(optional) string containing the longer description of the Tag
tags[].name
string

(mandatory) string containing the Tag name
tags[].sort_key
int

(optional) integer reflecting the Tag order set up in the Author Site
tags[].type
string

(mandatory) string containing 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": []
}
*/
Endpoint /itembank/tagging/hierarchies
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.
references
array

Array of strings

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
                }
            ]
        }
    ]
}
*/
Endpoint /itembank/tagging/hierarchies/nodes
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.
path
array

Ordered array of TagV2 Objects
reference
string

Reference of the Tag hierarchy to get nodes for.

Example

{
  "reference": "TagHierarchyTest",
  "path": [
      { "type": "author",   "name": "brianmoser" },
      { "type": "subject",  "name": "math" }
  ]
}

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1482285520,
        "records": 2
    },
    "data": [
        {
            "type": "course",
            "name": "commoncore",
            "description": "Common Core"
        },
        {
            "type": "course",
            "name": "example course",
        }
    [
}
*/
Endpoint /itembank/pools
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.
limit
integer

Restricts the number of records returned, with a maximum of 50.

Default: 50
next
string

A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
references
array

Array of strings. Up to 1000 references may be provided. Filters the resultset to the specified Item pools.
sort
string

Determines response sorting, can be desc or asc.

Default: desc
sort_field
string

Determines sort field, can be created to sort by time created or updated to sort by time updated

Default: created
status
array

Filter pools by their statuses, supports published, unpublished, pending or halted

Default: published, unpublished, pending and halted

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
  }
}
*/
Endpoint /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
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.
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[].overwrite
boolean		 [optional] If true, a pool with the given reference is emptied, if it exists, before being populated with the new content. Defaults to 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 (i.e. the Tag combination is treated as if the optional additional_tags array had not been set).
pools[].set_unpublished_to_published
boolean		 [optional] Setting this to true will allow an update of a pool, by setting any 'unpublished' content to 'published' status, then adding it to that pool. By default, you are prevented from storing unpublished content in Item bank pools.
Default: false.
pools[].description
string		 [optional] Description of the 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"
    }
  ]
}
*/
Endpoint /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
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.
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"
        }
    ]
}
*/

Provides a way to upload assets directly to Learnosity 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 /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
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.

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"
        }
    ]
}
*/

This option is used in the Learnosity local device assessment app. This is an enterprise product that needs to be specially enabled. Talk to Learnosity Support about how to access it.

Endpoint /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
v2019.2.LTS or later
integer

Returns content from the Item bank with the supplied ID.

The consumer making the request will need to be configured with a Primary Item bank, or have write access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console.

activity_references
array

Array of Activity references to be packaged. Up to 1000 references may be provided.
items
array

Array of Item object to be packaged.
item_references
array

Deprecated

Array of Item references to be packaged. Up to 1000 references may be provided.
base_directory
string

(optional) attribute, specifies the base directory for all content and assets, defaults to /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"
        }
    ]
}
*/
Endpoint /itembank/workflows
HTTP Method POST
Action Type get
Parameter Description
organisation_id
v2019.2.LTS or later
integer

(optional) 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.
limit
integer

(optional) Restricts the number of records returned, with a maximum of 50.

Default: 50
next
string

(optional) A string token used to request the next page of results. If a request would produce a resultset larger than `limit`, the return packet will include a string token in meta.next. Pass the token along with the original request parameters to retrieve the next page of results.
references
array

(optional) Filter by specific workflow references. Up to 1000 references may be provided.

References are case insensitive.

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
                        }
                    ]
                }
            ]
        }
    ]
}
*/
Endpoint /itembank/workflows
HTTP Method POST
Action Type set
Parameter Description
organisation_id
v2019.2.LTS or later
integer

(optional) 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.
workflows
array

(mandatory) An array of objects should be provided, each object representing a separate workflow.

The maximum number of array elements permitted is 50.
workflows[].reference
string

(mandatory) Reference of the workflow. Maximum of 150 characters, case insensitive and must only contain ASCII printable characters, except for double quotes, single quotes and accent.

Reference is used to activate workflow, for example while authoring Items, in Author API configuration.
workflows[].initial_state_reference
string

(mandatory) Initial state of the workflow. Maximum of 150 characters, case sensitive and should match one of the state references passed to workflows[].workflow_states[].

Initial state will be assigned to the Item automatically, once the Item is created.
workflows[].final_state_reference
string

(mandatory) Final state of the workflow. Maximum of 150 characters, case sensitive and should match one of the state references passed to workflows[].workflow_states[].

The Item in its final state will be automatically converted to published status.
workflows[].description
string

(optional) Description of the workflow. Maximum of 1000 characters.
workflows[].workflow_states
array

(mandatory) An array of objects should be provided, each object representing a separate state for workflow.
workflows[].workflow_states[].reference
string

(mandatory) Reference of the state. Maximum of 150 characters and case sensitive.
workflows[].workflow_states[].description
string

(optional) Description of the state. Maximum of 1000 characters.
workflows[].workflow_states[].label
string

(mandatory) Label of the state displayed in user interface. Maximum of 150 characters.
workflows[].workflow_states[].
workflow_transitions
array

(mandatory) An array of objects should be provided, each object representing a separate transition for state.
workflows[].workflow_states[].
workflow_transitions[].to_state_reference
string

(mandatory) Reference of the state the transition leads to. Maximum of 150 characters, case sensitive and should match one of the state references passed to workflows[].workflow_states[].
workflows[].workflow_states[].
workflow_transitions[].display_order
integer

(mandatory) Sorts state transitions in the user interface (smallest on top).

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": []
}
*/

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

Endpoint /itembank/playertemplates
HTTP Method POST
Action Type get
Parameter Description
organisation_id

integer

(optional) 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 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 /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 /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		 TagsV0 object

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

Example

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

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

Get Activity Base Templates (deprecated)

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 /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"
                        }
                    ]
                }
                */