Item Bank Endpoints

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

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 v1/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.

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 item bank items, 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.

tags.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": "reference": "SB_EG11Q11_1",
                        "organisation_id": 1,
                    },
                    {
                        "reference": "SB_EG11Q11_2",
                        "id": "reference": "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 v1/itembank/activities
HTTP Method POST
Action Type set
Parameter Description
activities
array

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

The maximum number of array elements permitted is 50.

activities[].base_template_id
string

The base template reference to be applied on the activity.

activities[].data
object

The JSON representation of an activity template.

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

Default: { "rendering_type": "assess" }

activities[].description
string

Admin only, viewable 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.

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
int

Optional. The ID of the organisation (bank) for which items will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

Example

{
    "activities": [
        {
            "reference": "ela-unit-1",
            "data": {
                "items": [
                    "demo1",
                    "demo3"
                ]
            },
            "tags": {
                "demo-tagtype-1": [
                    "tag1",
                    "tag2"
                ],
                "demo-tagtype-2": [
                    "tag3"
                ]
            },
            "description": "My activity",
            "status": "unpublished"
        }
    ]
}

/* Example Response:
{
    "meta": {
        "status": true
    },
    "data":[]
}
*/
Endpoint v1/itembank/activities/duplicate
HTTP Method POST
Action Type set
Parameter Description
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.

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 v1/itembank/activities/tags
HTTP Method POST
Action Type set
Parameter Description
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 v1/itembank/activities/tags
HTTP Method POST
Action Type update
Parameter Description
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": []
}
*/

No parameters applicable. The endpoint always returns all activity base templates.

Endpoint v1/itembank/activities/templates
HTTP Method POST
Action Type get

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": {
                            "saveIntervalDuration": 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"
        }
    ]
}
*/
Endpoint v1/itembank/items
HTTP Method POST
Action Type get
Parameter Description
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

  • dt_created,
  • dt_updated,
  • created_by,
  • last_updated_by,
  • max_score and
  • dynamic_content_data.

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 items by question types, specified as strings. Filters the resultset to items containing at least one of the specified question types.

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: published, unpublished

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.

tags.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
int

Optional. The ID of the organisation (bank) for which items will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

Example

{
    "references": [
        "QuestionRef1",
        "QuestionRef2"
    ],
    "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": 10
    },
    "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"
        ]
    }
}

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

{
    "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 v1/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[].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[].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[].note
string
Used only within the Learnosity Author Site
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[].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 called 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
int

Optional. The ID of the organisation (bank) for which items will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

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 v1/itembank/items/duplicate
HTTP Method POST
Action Type set
Parameter Description
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 v1/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
int

Optional. The ID of the organisation (bank) for which items will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

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 v1/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
int

Optional. The ID of the organisation (bank) for which items will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

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 that 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 v1/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

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 questions 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 question type codes, as strings eg ["mcq", "clozeassociation"]. See widget 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 v1/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
int

Optional. The ID of the organisation (bank) for which items will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

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. See Supported HTML for the list of supported HTML tags and attributes.

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 v1/itembank/questions/duplicate
HTTP Method POST
Action Type set
Parameter Description
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 that 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 v1/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

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 v1/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. See Supported HTML for the list of supported HTML tags and attributes.

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
int

Optional. The ID of the organisation (bank) for which items will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

Example

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

/* Example Response:
{
    "meta": {
        "status": true,
        "timestamp": 1396235761
    },
    "data": []
}
*/
Endpoint v1/itembank/features/duplicate
HTTP Method POST
Action Type set
Parameter Description
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 v1/itembank/tagging/tags
HTTP Method POST
Action Type get
Parameter Description
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 v1/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
int

Optional. The ID of the organisation (bank) for which tags will be imported into. Discuss this with Learnosity Support if in doubt.

If not specified, the default organisation of the requesting consumer is used.

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 v1/itembank/tagging/hierarchies
HTTP Method POST
Action Type get
Parameter Description
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 v1/itembank/tagging/hierarchies/nodes
HTTP Method POST
Action Type get
Parameter Description
path
array

Ordered array of TagV2 Objects

references
array

Array of strings

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 v1/itembank/pools
HTTP Method POST
Action Type get
Parameter Description
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 or pending

Default: published

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 v1/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
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] Set to true to allow the creation of a pool with unpublished content.
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 v1/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
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.

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 v1/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
int

Optional. The ID of the organisation for which to upload the assets.

If not specified, the default organisation of the requesting consumer is used. Performing uploads for a particular organisation requires "write" access.

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 unneccessary 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 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 Learnosity offline App which is being developed.

Endpoint v1/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 offline content package.

Parameter Description
activity_references
array

Array of activity references to be packaged

item_references
array

Array of item references to be packaged

base_directory
string

Optional attribute, specifies the base directory for all content and assets, defaults to /vendor/itembank

Example

{
    "item_references": [
        "item_reference_1"
    ],
    "activity_references": [
        "activity_reference_1"
    ]
}

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

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

Endpoint v1/itembank/tags
HTTP Method POST
Action Type get
Parameter Description
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 v1/itembank/tags
HTTP Method POST
Action Type set
Parameter Description
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": []
}
*/