Item Bank Endpoints
The Data API's /itembank/*
endpoints allow you to create, retrieve, and maintain Item bank content programmatically.
Usage
The format of requests to Data API use the following syntax:
https://data.learnosity.com/[LTS_VERSION]/itembank/*
For example, to use the 2023.3.LTS version and the 'Get Activities' Item bank endpoint, you would create a request like so:
https://data.learnosity.com/v2023.3.LTS/itembank/activities
Note: Data API usage is subject to rate limits. Read more here: Rate Limiting With the Data API.
Get Activities
Retrieve Activities from your Item bank.
You would want to use this to retrieve and load your Activities into your own application, for example.
Endpoint | /[LTS_VERSION]/itembank/activities |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
include object |
Properties to be returned in the response. (optional) See below for available attributes. |
include.activities array[string] |
Activity properties to be returned in the response including |
organisation_id integer |
Specifies the Item bank to retrieve Activities from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
item_pool_id string |
Specifies the Item pool from which to retrieve the Activities. See Using Item Pools to Create Content Snapshots for more information. |
item_references object |
Object with Only Activities containing all the Items with references in Note Only for Items belonging to the same Item bank as the Activity Note Not supported for Item pools. |
limit integer |
Restricts the number of records returned. Default: 50 records. |
maxtime integer | string |
A timestamp filter based on the value provided in the |
mintime integer | string |
A timestamp filter based on the value provided in the |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
references array |
Specifies the Activity template references to include. Maximum: 1000 references.
|
sort string |
Determines response sorting. Possible values:
Default: |
sort_field string |
Specifies the field to sort the results by. Possible values:
Default: |
status array[string] |
Filter Activities by their statuses. (optional) Possible values:
Default: (none) |
tags array | object |
Filter Activities by Tags, each array element is a TagsV2 Object or TagSearchByType object.
When searching using multiple Tags of different types, specify the |
advanced_tags object |
Filter Activities using one of the following tagging conditions. Possible attributes:
At least one of the above keys must be present. See Understanding Tag Formats for Content Creation and Filtering for more information. |
Example
{
"advanced_tags": {
// Activities must have all of these tags...
"all": [
{ "type": "subject", "name": "English" }
],
// ...AND have at least one of these tags...
"either": [
{ "type": "grade", "name": "6" },
{ "type": "grade", "name": "7" }
],
// ...AND have none of these tags...
"none": [
{ "type": "grade", "name": "5" },
{ "type": "grade", "name": "8" }
]
},
"include" : {
"activities": ["dt_created"],
}
// Optionally include additional generic parameters.
...
}
/* Example Response with Items defined as object:
{
"meta": {
"status":true,
"timestamp":1389192595
},
"data": [
{
"reference":"SB_EG11Q11",
"description":"Smarter Balanced Practice Test ELA",
"data": {
"activity_id": "smtest_1",
"name": "SM Test #1",
"rendering_type": "assess",
"state": "initial",
"type": "submit_practice",
"items":
{
"reference": "SB_EG11Q11_1",
"id": "SB_EG11Q11_1",
"organisation_id": 1,
},
{
"reference": "SB_EG11Q11_2",
"id": "SB_EG11Q11_2",
"organisation_id": 1,
}
],
"config": {
"navigation": {
"show_next": true,
"show_prev": false,
"show_fullscreencontrol": false,
"show_progress": true,
"show_submit": true,
"show_title": true,
"show_save": false,
"show_calculator": false,
"scroll_to_top": false,
"scroll_to_test": false,
"show_itemcount": true,
"toc": false,
"warning_on_change": true,
"skip_submit_confirmation": true
}
}
},
"status": "published",
"tags": {
"course": [
"commoncore"
]
},
"dt_created": "2014-11-27 05:32:15",
"adaptive" : {
"difficulty": 1.2,
"operational_exposure": null,
"seeding_exposure": null
}
}
]
}
The Items might also be returned as an array of strings, e.g.:
"items": [
"SB_EG11Q11_1",
"SB_EG11Q11_2"
]
*/
Set Activities
Create or update Activities in your Item bank.
You would want to use this to import or bulk update Activities, or import your own Activities from another source, for example.
Endpoint | /[LTS_VERSION]/itembank/activities |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
activities array[object] |
An array of objects where each represents a separate Activity. See below for supported attributes. Maximum: 50 entries. |
activities[].base_template_id string Deprecated |
The base template reference to be applied on the Activity. |
activities[].data object |
The JSON representation of an Activity. All supported Activity properties can be found in the Items API documentation. Default: |
activities[].data.items array |
Item definitions to be added to the Activity. See the Items API documentation for the supported format of Items.
Note
Items can be specified as either an object definition or a string reference. It is important to choose one type format and use it consistently in other parts of the |
activities[].data.config object |
The initialization options for the Activity. See the Items API documentation for supported options. |
activities[].data.sections array |
Define sections for the Activity. Sections allows you to split an Activity into separate groups of Items. See Items API sections for more information and refer to the caveats section for important usage details. |
activities[].description string |
A description for the Activity, visible only to authors via the Author API and Learnosity Author Site. |
activities[].reference string |
The reference for the Activity. Maximum: 150 ASCII characters Note: double quotes, single quotes, and accent characters are not allowed. |
activities[].status string |
Status of the Activity. See Changing The Activity Status In The Activity Editor for more information. Note: The Activity must be set to Default: |
activities[].tags object |
Tags to assign to the Activity. See TagsV2 for more information. |
activities[].title string |
A human readable title used to identify an Activity which can be seen in the Author API and Learnosity Author Site. |
meta object |
(optional) A metadata object which will be applied to all Activities in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Activities. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Activities. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Activities. Maximum: 255 characters. |
organisation_id integer |
Specifies the Item bank to create Activities. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Example
{
"activities": [
{
"reference": "ela-unit-1",
"data": {
"items": [
"ela_item_1",
"ela_item_2"
],
"config": {
"regions": "main"
},
"rendering_type": "assess"
},
"tags": {
"demo-tagtype-1": [
"tag1",
"tag2"
],
"demo-tagtype-2": [
"tag3"
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true
},
"data": []
}
*/
Duplicate Activities
Duplicate existing Activities, including all associated Items, Questions, and Features in your Item bank.
You would want to use this to duplicate your previous year's Activities for use in the current year, for example.
This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs
endpoint and the returned job_reference
to check the status of the job.
Endpoint | /[LTS_VERSION]/itembank/activities/duplicate |
---|---|
HTTP Method | POST |
Action Type | set |
Returns | A JSON object containing a job_reference that can be submitted to the jobs endpoint to track the completion of the asynchronous request. |
Parameter | Description |
organisation_id integer |
Specifies the Item bank in which to read and duplicate Activities. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
activities array[object] |
An array of objects where each object represents an Activity to be duplicated. Maximum: 10 Activities to be duplicated. |
activities[].reference string |
Specifies the reference of an Activity you want to duplicate. |
activities[].new_reference string |
(optional) Specifies the reference of the newly duplicated Activity. If this is not specified, a reference for the duplicated Activity will be automatically generated. Note: The new Activity reference must not already exist in your Item bank. |
duplicate_shared_passages boolean |
Specifies whether shared passages in Items will be duplicated. By default, shared passages are not duplicated and are referenced from the original Item instead. Default: |
meta object |
(optional) A metadata object which will be applied to all duplicated Activities in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Activities. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Activities. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Activities. Maximum: 255 characters. |
Example
{
"activities": [
{
"reference": "ACTIVITY_7",
"new_reference": "DuplicatedActivity"
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1512120158
},
"data": {
"job_reference": "69a3c789-0273-413f-bb7b-6e4f48ac5cbf" // Can be used to query the job database to find out when duplication is complete.
}
}
*/
Set Activities Tags
Overwrite Tags for Activities in your Item bank.
You would want to use this to make bulk replacements of Tags for many Activities.
Important: existing Tags assigned to Activities will be removed from the Activity and replaced with the new Tags.
Endpoint | /[LTS_VERSION]/itembank/activities/tags |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
activities array |
A list of Activity and Tag combinations to be processed. Maximum: 50 Activities. |
activities[].reference string |
Activity reference. |
activities[].tags object |
|
meta object |
(optional) A metadata object which will be applied to all Activities in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the modified Activities or Tags. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or affected Activities or Tags. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the affected Activities or Tags. Maximum: 255 characters. |
Example
{
"activities": [
{
"reference": "activity1",
"tags": {
"demo-tagtype-1": [
"tag1",
"tag2"
],
"demo-tagtype-2": [
"tag3"
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true
},
"data": []
}
*/
Append Activities Tags
Add new Tags to Activities in your Item bank. Existing Tags assigned to these Activities will not be removed.
You would want to use this to make bulk additions of Tags to Activities.
Endpoint | /[LTS_VERSION]/itembank/activities/tags |
---|---|
HTTP Method | POST |
Action Type | update |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
activities array |
Array of Activity/Tag objects. The maximum number of array elements permitted is 50. |
activities[].reference string |
Activity reference |
activities[].tags object |
|
meta object |
(optional) A metadata object which will be applied to all Activities in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the modified Activities. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the affected Activities or Tags. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the affected Activities or Tags. Maximum: 255 characters. |
Example
{
"activities": [
{
"reference": "activity1",
"tags": {
"demo-tagtype-1": [
"tag4",
"tag5"
],
"demo-tagtype-2": [
"tag6"
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1499223766
},
"data": []
}
*/
Get Items
Retrieves Items from the specified Item bank.
You would want to use this to use the Item data in your own application.
By default, all Items are returned (all published, unpublished and archived Items). This can be filtered by status
.
Endpoint | /[LTS_VERSION]/itembank/items |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
authoring_workflow object |
(optional) Include Items with a specific workflow reference and its states. See below for supported attributes. |
authoring_workflow.reference string |
Include Items by the workflow reference they belong to. Important: the workflow reference is mandatory if the |
authoring_workflow.states array[string] |
(optional) Include Items by their workflow states. By default, returns all Items regardless of their workflow state. Default: ["Unassigned", all states of the workflow specified by |
created_by array |
Include Items with a specific user ID that created the Item. |
include object |
(optional) The Item properties to be returned in the response. See below for supported attributes. |
include.items array[string] |
(optional) Item properties to be returned in the response including:
Note
The |
item_pool_id string |
Retrieves content from the specified Item pool instead of the Item bank. |
limit integer |
Restricts the number of records returned. Default: 50 records. |
maxtime int | string |
A timestamp filter based on the value provided in the |
mintime int | string |
A timestamp filter based on the value provided in the |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
questions object |
(optional) Include Items containing a specific Question reference or type. |
questions.references array[string] |
Include Items that contain at least one of the specified Question references. Maximum: 1000 Question references. |
questions.types array[string] |
Include Items that contain any specified Question or Feature types, for example, See Question & Feature type codes for a full list. |
references array[string] |
Include specific Item references in the results. Maximum: 1000 references.
|
scoring_type array |
Include Items by their scoring types. Possible values:
See Per Question, Dichotomous, And Dependent (EBSR) Item Scoring With Examples for more information. |
sort string |
Determines response sorting. Possible values:
Default: |
sort_field string |
Specifies the field to sort the results by. The options are as follows:
Default: |
status array |
Include Items by their statuses, supports Default: all Items are returned, (all published, unpublished and archived Items). |
tags array[object] |
Include Items by Tags. Each element must be a TagV2 Object or TagSearchByType Object.
When searching using multiple Tags of different types, use |
advanced_tags object |
Specify more complex search queries based on Tags, including optional or negative criteria. At least one of the following object keys must be present:
See AdvancedTagSearchParams (Data API) for more information. |
organisation_id integer |
Specifies the Item bank to retrieve Items from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Example
// Find Items by Tags
{
"limit": 5,
"advanced_tags": {
// Items must have all of these Tags...
"all": [
{
"type": "subject",
"name": "English"
}
],
// ...AND have at least one of these Tags...
"either": [
{
"type": "grade",
"name": "6"
},
{
"type": "grade",
"name": "7"
}
],
// ...AND have none of these Tags...
"none": [
{
"type": "grade",
"name": "5"
},
{
"type": "grade",
"name": "8"
}
]
},
"include": {
"items": ["dt_created"]
}
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1470291213,
"next": "1445216251.1165015",
"records": 5
},
"data": [
{
"reference": "ce76962d-d80d-4d4a-b755-20744d2fdb68",
"title": "example title",
"workflow": null,
"note": null,
"source": null,
"definition": {
"regions": [
{
"widgets": [
{ "reference": "f2f1bf47-d22d-4627-8d39-c460f00c183f" }
],
"type": "column",
"width": "50"
},
{
"widgets": [
{ "reference": "877883fb-108e-4736-a299-3ae483d7b0e5" },
{ "reference": "755dfab9-8687-4692-ab5d-2048a6af997f" }
],
"type": "column",
"width": "50"
}
],
"template": "dynamic"
},
"description": "",
"status": "published",
"questions": [
{
"reference": "877883fb-108e-4736-a299-3ae483d7b0e5",
"type": "mcq"
},
{
"reference": "755dfab9-8687-4692-ab5d-2048a6af997f",
"type": "longtext"
}
],
"features": [
{
"reference": "f2f1bf47-d22d-4627-8d39-c460f00c183f",
"type": "sharedpassage"
}
],
"tags": {
"author": ["Smarter Balanced Practice Test"],
"course": ["commoncore"],
"Grade": ["7"],
"questiontype": ["longtext","mcq"],
"subject": ["English"]
}
},
...
]
}
*/
// Find Items by Item references
{
"references": [
"Grade7_ELA_1021",
"Grade7_ELA_1022"
],
"include": {
"items": [
"dt_created",
"dt_updated",
"authoring_workflow"
]
}
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1470291591,
"records": 2
},
"data": [
{
"reference": "Grade7_ELA_1021",
"workflow": null,
"metadata": null,
"note": null,
"source": null,
"definition": {
"regions": [
{
"widgets": [
{ "reference": "fe359969-5170-4a57-b864-1870698f6aea" },
{ "reference": "7550b655-74da-422f-9368-cb5a851395f2" }
],
"type": "column",
"width": "50"
},
{
"widgets": [
{ "reference": "a3a57364-9954-44bf-a2e4-feb1c17efdc5" }
],
"type": "column",
"width": "50"
}
],
"template": "dynamic"
},
"description": "",
"status": "published",
"questions": [
{
"reference": "7550b655-74da-422f-9368-cb5a851395f2",
"type": "mcq"
},
{
"reference": "a3a57364-9954-44bf-a2e4-feb1c17efdc5",
"type": "shorttext"
}
],
"features": [
{
"reference": "fe359969-5170-4a57-b864-1870698f6aea",
"type": "formulainput"
}
],
"tags": {},
"dt_created": "2016-08-03 15:39:40",
"dt_updated": "2016-08-03 15:39:47",
"authoring_workflow": {
"reference": "Default workflow",
"state": "Approved"
}
},
{
"reference": "Grade7_ELA_1022",
"workflow": null,
"metadata": null,
"note": null,
"source": null,
"definition": {
"widgets": [
{ "reference": "d7843b0d-da85-4686-b347-7b7c563d2abf" },
{ "reference": "9d3dd429-0ec9-4038-a932-6ea69676619a" }
],
"template": "dynamic"
},
"description": "",
"status": "published",
"questions": [
{
"reference": "d7843b0d-da85-4686-b347-7b7c563d2abf",
"type": "mcq"
},
{
"reference": "9d3dd429-0ec9-4038-a932-6ea69676619a",
"type": "mcq"
}
],
"features": [],
"tags": {},
"dt_created": "2016-08-03 02:35:06",
"dt_updated": "2016-08-03 02:43:14",
"authoring_workflow": null
}
]
}
*/
// Find Items including specific Question types
{
"questions": {
"types": [
"imageclozetext",
"imageclozeassociation"
]
}
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1470292580,
"next": "1441094282.886429",
"records": 10
},
"data": [
{
"reference": "labelimage_heart_example",
"workflow": null,
"metadata": {
"scoring_type": "per-question",
"acknowledgements": null
},
"note": null,
"source": null,
"definition": {
"widgets": [
{ "reference": "cf35406a-88ba-4294-bca2-d013fa2bbd11" }
],
"template": "dynamic"
},
"description": "",
"status": "published",
"questions": [
{
"reference": "cf35406a-88ba-4294-bca2-d013fa2bbd11",
"type": "imageclozetext"
}
],
"features": [],
"tags": {}
},
{
"reference": "anatomy_103052b",
"workflow": null,
"note": null,
"source": null,
"definition": {
"regions": [
{
"widgets": [
{ "reference": "9cb5ca80-3418-4f2c-aef8-c905fff28501" }
],
"type": "column",
"width": "50"
},
{
"widgets": [
{ "reference": "d2f97a5a-7975-4b26-b050-8761f3443f29" },
{ "reference": "2fb9049a-bc3e-4203-8f40-ccd5048c5807" }
],
"type": "column",
"width": "50"
}
],
"template": "dynamic"
},
"description": "",
"status": "published",
"questions": [
{
"reference": "d2f97a5a-7975-4b26-b050-8761f3443f29",
"type": "mcq"
},
{
"reference": "2fb9049a-bc3e-4203-8f40-ccd5048c5807",
"type": "imageclozeassociation"
}
],
"features": [
{
"reference": "9cb5ca80-3418-4f2c-aef8-c905fff28501",
"type": "sharedpassage"
}
],
"tags": {}
},
...
]
}
*/
Set Items
Creates or updates Items in your Item bank.
You would want to use this to import or bulk update Items, or import your own Items from another source, for example.
Endpoint | /[LTS_VERSION]/itembank/items |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
items array |
An array of objects should be provided, each object representing a separate Item. The maximum number of array elements permitted is 50. |
items[].adaptive object |
(optional) The adaptive data to be used in the assessments as per Adaptive Assessments. |
items[].adaptive.difficulty integer |
(optional) Set difficulty of the Item. See Adaptive Assessments for more information. |
items[].authoring_workflow object |
(optional) Object containing the Item workflow data. See below for supported attributes. |
items[].authoring_workflow.reference string |
(mandatory) Reference of the workflow the Item should use. |
items[].authoring_workflow.state string |
(mandatory) Workflow state that should be assigned to the Item. |
items[].definition object |
The Item layout definition. See the Item Definition for more information. |
items[].description string |
The description of the Item. This field only appears within the Learnosity Author Site or Author API for authors. |
items[].dynamic_content_data object |
Data for dynamic content Items. See What Is Dynamic Content? for more information. |
items[].features array[string] |
A list of Feature references to be included in the Item. |
items[].metadata object |
The general metadata attached to the Item. See below for supported attributes. |
items[].metadata.acknowledgements string |
Provide an acknowledgement of assets owned by other organizations which are used in the assessment, for copyright purposes, such as images or other media content. HTML values are permitted. |
items[].metadata.scoring_type string |
Possible values:
See Per Question, Dichotomous, And Dependent (EBSR) Item Scoring With Examples for more information. |
items[].new_reference string |
(optional) Update an Item's reference with a new value. When |
items[].note string |
General text field for authors to leave notes which are not shown to the learner. |
items[].questions array[object] |
A list of Questions to include in the Item. See below for supported attributes. |
items[].questions[].reference string |
The individual Question reference. Must contain only letters, numbers, underscores, or dashes. |
items[].reference string |
The reference for the Item. Note: double quotes, single quotes, and accent characters are not allowed. Maximum: 150 ASCII characters. |
items[].source string |
The origins of the content for the Item, for example, the name of the book where the content is sourced from. This field is only for authors and will not be shown to learners. |
items[].status string |
The workflow status of the Item. Possible values:
Note: the status must be Default: |
items[].tags object |
TagsV2 Object |
items[].title string |
A human readable title used to identify an Item which can be seen in the Author API and Learnosity Author Site. Maximum: 150 characters. |
meta object |
(optional) A metadata object which will be applied to all Items created in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both The user ID can also be passed to GET /itembank/items to filter by Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Items. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Items. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Items. Maximum: 255 characters. |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Example
{
"items": [
{
"reference": "ff685a20-12c7-42ce-a592-b046f2f07502",
"metadata": null,
"definition": {
"widgets": [
{ "reference": "88879936-952c-442a-b3c9-05e95b6ed91f" }
]
},
"status": "published",
"questions": [
{ "reference": "88879936-952c-442a-b3c9-05e95b6ed91f" }
],
"tags": {}
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1700294472
},
"data": []
}
*/
Duplicate Items
Duplicates Items (including all associated Questions and Features) in your Item bank.
You would want to use this to bulk duplicate many Items at once, to create the basis for a new annual assessment, for example.
Endpoint | /[LTS_VERSION]/itembank/items/duplicate |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
organisation_id integer |
Specifies the Item bank in which to read and duplicate Items. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
items array |
An array of objects should be provided, each object representing an Item to be duplicated. Duplication is deep, i.e. questions are also duplicated. The maximum number of array elements permitted is 50. |
items[].reference string |
Specifies the reference of an Item you want to duplicate. |
items[].new_reference string |
An optional parameter specifying the reference of the duplicated Item. |
duplicate_shared_passages boolean |
If set to true, shared passages will be duplicated. By default, it is false, i.e. shared passages are reused. |
meta object |
(optional) A metadata object which will be applied to all Items created in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the created Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Items. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Items. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Items. Maximum: 255 characters. |
Example
{
"items": [
{
"reference": "6f065658-2e19-49a5-9267-9a0d7e2b8afe",
"new_reference": "DuplicatedItem"
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1512123317
},
"data": {
"6f065658-2e19-49a5-9267-9a0d7e2b8afe": {
"reference": "DuplicatedItem",
"title": "Test",
"content": "<div class="row"><div class="col-xs-12"><span class="learnosity-response question-e27e8fa1-f984-4132-b0ba-d0b6f66205bf"></span><span class="learnosity-feature feature-f86c1568-be40-4228-a21f-8fb2c5409482"></span></div></div>",
"workflow": null,
"metadata": null,
"note": null,
"source": null,
"definition": {
"widgets": [
{
"reference": "e27e8fa1-f984-4132-b0ba-d0b6f66205bf"
},
{
"reference": "f86c1568-be40-4228-a21f-8fb2c5409482"
}
],
"template": "dynamic"
},
"description": "",
"status": "published",
"questions": [
{
"reference": "e27e8fa1-f984-4132-b0ba-d0b6f66205bf",
"type": "clozeassociation"
}
],
"features": [
{
"reference": "f86c1568-be40-4228-a21f-8fb2c5409482",
"type": "sharedpassage"
}
],
"tags": {
"integration": [
"test"
]
},
"adaptive": {
"difficulty": null,
"operational_exposure": null,
"seeding_exposure": null
}
}
}
}
*/
Set Items Tags
Assign new Tags to specified Items.
You would want to use this to change the Tags on many Items at once, for example.
Important: existing Tags assigned to Items will be deleted and replaced with the new Tags.You would want to use this to bulk assign Tags to many Items at once, for example.
Endpoint | /[LTS_VERSION]/itembank/items/tags |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
items array |
Array of Item/Tag objects. The maximum number of array elements permitted is 50. |
items[].reference string |
Item reference |
items[].tags object |
|
meta object |
(optional) A metadata object which will be applied to all Items in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both The user ID can also be passed to GET /itembank/items to filter by Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the affected Items or Tags. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the affected Items or Tags. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the affected Items or Tags. Maximum: 255 characters. |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Example
{
"items": [
{
"reference": "item1",
"tags": {
"demo-tagtype-1": [
"tag1",
"tag2"
],
"demo-tagtype-2": [
"tag3"
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true
},
"data": []
}
*/
Append Items Tags
Assign new Tags to Items.
You would want to use this to assign Tags to many Items at once, for example.
Note: Existing Tags assigned to Items will not be deleted.Endpoint | /[LTS_VERSION]/itembank/items/tags |
---|---|
HTTP Method | POST |
Action Type | update |
Parameter | Description |
items array |
Array of Item/Tag objects. The maximum number of array elements permitted is 50. |
items[].reference string |
Item reference |
items[].tags object |
|
meta object |
(optional) A metadata object which will be applied to all Items in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the modified Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both The user ID can also be passed to GET /itembank/items to filter by Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the affected Items or Tags. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the affected Items or Tags. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of affected Items or Tags. Maximum: 255 characters. |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Example
{
"items": [
{
"reference": "item1",
"tags": {
"demo-tagtype-1": [
"tag1",
"tag2"
],
"demo-tagtype-2": [
"tag3"
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true
},
"data": []
}
*/
Get Questions
Retrieves Questions from your Item bank.
You would want to use this to extract existing Questions (JSON format) to perform a backup or re-use them in your application, for example.
If item_references
are provided, Questions associated with the provided Item reference(s) will be returned.
Note
Any Features associated with the provided references
or item_references
will not be returned from this endpoint. Instead, Features can be retrieved using the dedicated itembank/features endpoint.
Endpoint | /[LTS_VERSION]/itembank/questions |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
include object |
(optional) Properties to be returned in the response. See below for supported attributes. |
include.questions array[string] |
(optional) Question properties to be returned in the response which can be |
organisation_id integer |
Specifies the Item bank to retrieve Questions from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
item_pool_id string |
Return content from an Item pool instead of the Item bank |
item_references array[string] |
(optional) Include Questions contained in at least one of the specified Items. Questions associated with the provided Item reference(s) will be returned. The result will be an object with Item references as keys, and an array of associated Questions as the values. Maximum: 1000 Item references. Example
|
limit integer |
Restricts the number of records returned. Default: 50 records. |
maxtime int | string |
A timestamp filter based on the value provided in the |
mintime int | string |
A timestamp filter based on the value provided in the |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
references array[string] |
A list of Question references. Maximum: 1000 Question references. |
sort string |
Determines response sorting. Possible values:
Default: |
sort_field string |
Specifies the field to sort the results by. The options are as follows:
Default: |
types array |
Array of strings. Can be any Question/Feature/Widget type codes e.g. |
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"
},
...
]
}
*/
Set Questions
Creates or overwrites Questions in your Item bank.
You would want to use this to bulk create new Questions for use in Items or import content from another source, for example.
Important: existing Questions with the same reference will be overwritten with the new properties.
Endpoint | /[LTS_VERSION]/itembank/questions |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
meta object |
(optional) A metadata object which will be applied to all Questions created in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Questions, and will be shown in Learnosity Author Site when viewing the history of changes on a Question. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Questions. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Questions. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Questions. Maximum: 255 characters. |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
questions array[object] |
The Questions you want to set, defined as a list of objects where each represents a separate Question. See below for supported attributes. Maximum: 50 object definitions. |
questions[].type string |
Specifies the Question type. See Question & Feature Codes for Data API filtering for a full list of Question type codes. |
questions[].reference string |
A unique reference for the Question. Must contain only letters, numbers, underscores, or dashes. Maximum: 150 characters. |
questions[].data object |
The raw Question data (JSON). See Question Types for a list of all possible attributes for every Question type. Note: the HTML markup will be automatically validated and any invalid tags or attributes may be removed for security purposes. See the list of supported HTML tags. |
Example
{
"questions": [
{
"type": "mcq",
"reference": "dataapi_test_001",
"data": {
"options": [
{
"value": "0",
"label": "John will have more apples and more oranges than Lucy."
},
{
"value": "1",
"label": "John will have less apples and less oranges than Lucy."
},
{
"value": "2",
"label": "John will have more apples than Lucy, but Lucy has more oranges."
},
{
"value": "3",
"label": "John will have more oranges than Lucy, but Lucy has more apples."
}
],
"stimulus": "This is the stem",
"type": "mcq",
"validation": {
"scoring_type": "exactMatch",
"valid_response": [
{
"value": [
"0"
],
"score": 1
}
]
}
}
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1396235761
},
"data": []
}
*/
Duplicate Questions
Duplicates Questions in your Item bank.
You would want to use this to bulk duplicate many Questions at once, to create the basis for a new annual assessment, for example.
Endpoint | /[LTS_VERSION]/itembank/questions/duplicate |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
organisation_id integer |
Specifies the Item bank in which to read and duplicate the Questions. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
item_references array |
An array of Item references for which Questions should be duplicated. |
duplicate_shared_passages boolean |
If set to true, shared passages will be duplicated. By default, it is false, i.e. shared passages are not duplicated. |
meta object |
(optional) A metadata object which will be applied to Questions created in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the created Questions, and will be shown in Learnosity Author Site when viewing the history of changes on the Questions. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Questions. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Questions. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Questions. Maximum: 255 characters. |
Example
{
"item_references": ["4bb30393-1fef-403b-ac5b-153bc9d1caf8"]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1512636002
},
"data": {
"4bb30393-1fef-403b-ac5b-153bc9d1caf8": {
"aa205cc7-402a-48e5-9cff-460c9f02fc24": {
"type": "mcq",
"widget_type": "response",
"reference": "ef0c22cb-0d3e-4d36-ab34-26e25d65f337",
"data": {
"options": [
{
"label": "[Choice A]",
"value": "0"
},
{
"label": "[Choice B]",
"value": "1"
}
],
"stimulus": "<p>[This is the stem.]</p>",
"type": "mcq",
"validation": {
"scoring_type": "exactMatch",
"valid_response": {
"score": 1,
"value": [
""
]
}
},
"ui_style": {
"type": "horizontal"
}
},
"metadata": {
"name": "Multiple choice – standard",
"template_reference": "9e8149bd-e4d8-4dd6-a751-1a113a4b9163"
}
}
}
}
}
*/
Get Features
Retrieves Features from your Item bank.
You would want to use this to extract existing Features (JSON format) to perform a backup or re-use them in your application, for example.
If item_references
are provided, Features associated with the provided Item reference(s) will be returned.
Note
Any Questions associated with the given references
or item_references
will not be returned from this endpoint. Questions can be retrieved using the dedicated itembank/questions endpoint.
Endpoint | /[LTS_VERSION]/itembank/features |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
include object |
(optional) Properties to be returned in the response. See below for supported attributes. |
include.features array |
(optional) Feature properties to be returned in the response including |
organisation_id integer |
Specifies the Item bank to retrieve Features from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
item_pool_id string |
Return content from an Item pool instead of the Item bank |
item_references array |
Array of strings. Up to 1000 Item references may be provided. Filters the resultset to features contained in at least one of the specified Items. |
limit integer |
Restricts the number of records returned. Default: 50 records. |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
references array[string] |
Up to 1000 Question references may be provided. |
sort string |
Determines response sorting. Possible values:
Default: |
sort_field string |
Specifies the field to sort the results by. The options are as follows:
Default: |
types array |
Array of Feature type codes, as strings eg |
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"
}
},
...
]
}
*/
Set Features
Creates or overwrites Features in your Item bank.
You would want to use this to bulk create new Features for use in Items or import content from another source, for example.
Important: existing Features with the same reference will be overwritten with the new properties.
Endpoint | /[LTS_VERSION]/itembank/features |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
features array |
An array of objects should be provided, each object representing a separate Feature. The maximum number of array elements permitted is 50. |
features[].type string |
Feature type code, see Widget codes for a full list. |
features[].reference string |
A unique reference for the Feature, must contain only letters, numbers, underscore or dash. Maximum length 150 characters. |
features[].data object |
Feature type object data Invalid HTML markup might be removed. |
meta object |
(optional) A metadata object which will be applied to all Features created in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Features, and will be shown in Learnosity Author Site when viewing the history of changes on the Features. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the new or modified Features. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the new or modified Features. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the new or modified Features. Maximum: 255 characters. |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Example
{
"features": [
{
"type": "calculator",
"reference": "myfeature01",
"data": {
"mode": "basic",
"type": "calculator"
}
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1396235761
},
"data": []
}
*/
Duplicate Features
Duplicates Features in your Item bank.
You would want to use this to bulk duplicate many Features at once, to create the basis for a new annual assessment, for example.
Endpoint | /[LTS_VERSION]/itembank/features/duplicate |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
organisation_id integer |
Specifies the Item bank in which to read and duplicate the Features. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
item_references array |
An array of Item references for which Features should be duplicated. |
duplicate_shared_passages boolean |
If set to true, shared passages will be duplicated. By default, it is false, i.e. shared passages are not duplicated. |
meta object |
(optional) A metadata object which will be applied to all Features created in this request. See below for supported attributes. |
meta.user object |
(optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Features, and will be shown in Learnosity Author Site when viewing the history of changes on the Features. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created Features. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created Features. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created Features. Maximum: 255 characters. |
Example
{
"item_references": ["4bb30393-1fef-403b-ac5b-153bc9d1caf8"]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1512636002
},
"data": {
"4bb30393-1fef-403b-ac5b-153bc9d1caf8": {
"aa205cc7-402a-48e5-9cff-460c9f02fc24": {
"type": "mcq",
"widget_type": "response",
"reference": "ef0c22cb-0d3e-4d36-ab34-26e25d65f337",
"data": {
"options": [
{
"label": "[Choice A]",
"value": "0"
},
{
"label": "[Choice B]",
"value": "1"
}
],
"stimulus": "<p>[This is the stem.]</p>",
"type": "mcq",
"validation": {
"scoring_type": "exactMatch",
"valid_response": {
"score": 1,
"value": [
""
]
}
},
"ui_style": {
"type": "horizontal"
}
},
"metadata": {
"name": "Multiple choice – standard",
"template_reference": "9e8149bd-e4d8-4dd6-a751-1a113a4b9163"
}
}
}
}
}
*/
Get Tags
Retrieve Tags from your Item bank.
You would want to use this to retrieve specific Tags for use in your own application, for example.
Endpoint | /[LTS_VERSION]/itembank/tagging/tags |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to retrieve Tags. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
item_pool_id string |
Returns content from an Item pool instead of the Item bank |
limit integer |
Restricts the number of records returned. Default: 50 records. |
names array[string] |
A list of Tag names to retrieve. |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
sort string |
Determines response sorting. Possible values:
Default: |
sort_field string |
Specifies the field to sort the results by. Possible values:
Default: |
types array[string] |
A list of Tag types to retrieve. Note: Tag types returned unless the |
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"
}
]
}
*/
Set Tags
Creates or overwrites Tags in your Item bank.
You would want to use this to bulk create new Tags to assign to Items and Activities.
Important: existing Tags with the same type
and name
will be overwritten with the new values.
Endpoint | /[LTS_VERSION]/itembank/tagging/tags |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
meta object |
(optional) A metadata object which will be applied to all Tags created in this request. See below for supported attributes. |
meta.user object |
(optional) Object. Contains user details of the user issuing the create or update operation in this request. The user details are recorded in the audit trail for each of the new or modified Tags. Default: |
meta.user.id string |
(mandatory) ID of the user issuing this request. Important: If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided ( Note: The user ID value is shown in the Learnosity Author Site audit trail if both Maximum: 50 characters. |
meta.user.firstname string |
(optional) First name of the user issuing the request. This first name is recorded in the audit trail for each of the created or updated Tags. Maximum: 50 characters. |
meta.user.lastname string |
(optional) Last name of the user issuing the request. This last name is recorded in the audit trail for each of the created or updated Tags. Maximum: 50 characters. |
meta.user.email string |
(optional) Email address of the user issuing the request. This email address is recorded in the audit trail for each of the created or updated Tags. Maximum: 255 characters. |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
tags array[object] |
An array of TagV2 objects should be provided, each object representing a separate Tag type or Tag combination. Maximum: 1000 TagV2 objects. |
tags[].description string |
A longer description for the Tag. This may be provided as |
tags[].name string |
(mandatory) The Tag name. |
tags[].sort_key integer |
The Tag order set up in the Author Site. |
tags[].type string |
(mandatory) The Tag type. |
Example
{
"tags": [
{
"type": "course",
"name": "Common Core",
"sort_key": 1,
"description": "common core subjects"
},
{
"type": "subject",
"name": "Maths",
"sort_key": 3,
"description": "mathematics"
},
{
"type": "subject",
"name": "English",
"sort_key": 2,
"description": "English literature and comprehension"
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1396235761
},
"data": []
}
*/
Get Tag Hierarchies
Retreives the hierarchy of Tag types for the specified hierarchy references.
You would want to use this to retrieve specific Tag hierarchies for use in your own application, for example.
Note: each returned Tag type represents one level of the hierarchy. Each Tag within a level is considered as a "node".
See How Do Tag Hierarchies Work? for more information.
Endpoint | /[LTS_VERSION]/itembank/tagging/hierarchies |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to retrieve the Tag Hierarchies from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
references array[string] |
A list of hierarchy references to retrieve. |
Example
{
"references": [ "TagHierarchyTest" ],
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1490241998,
"records": 1
},
"data": [
{
"reference": "TagHierarchyTest",
"tag_types": [
{
"name": "author",
"description": null
},
{
"name": "subject",
"description": null
},
{
"name": "course",
"description": null
},
{
"name": "questiontype",
"description": null
}
]
}
]
}
*/
Get Tag Hierarchy Nodes
Retrieves the next node in a Tag hierarchy from your Item bank.
You would want to use this to retrieve specific Tag hierarchy nodes for use in your own application, for example.
See How Do Tag Hierarchies Work? for more information.
Endpoint | /[LTS_VERSION]/itembank/tagging/hierarchies/nodes |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to retrieve the Tag hierarchy nodes from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
path array[TagsV2] |
An ordered array of TagV2 objects. |
reference string |
The reference of the Tag hierarchy to get nodes for. |
Example
{
"reference": "TagHierarchyTest",
"path": [
{ "type": "author", "name": "J.D. Salinger" },
{ "type": "subject", "name": "English" }
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1482285520,
"records": 2
},
"data": [
{
"type": "course",
"name": "commoncore",
"description": "Common Core"
},
{
"type": "course",
"name": "example course",
}
[
}
*/
Get Pools
Retrieve a list of Item pools for the specified Item bank.
You would want to use this to see all available Item pools for your Item bank and retrieve content from the desired Item pool.
See Using Item Pools to Create Content Snapshots for more information.
Endpoint | /[LTS_VERSION]/itembank/pools |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to retrieve Item pools from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
limit integer |
Restricts the number of records returned. Default: 50 records. |
next string |
A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
references array[string] |
A list of Item pool references to retrieve. |
sort string |
Determines response sorting. Possible values:
Default: |
sort_field string |
Specifies the field to sort the results by. The options are as follows:
Default: |
status array[string] |
Include Item pools by their statuses. Possible values:
Default: all statuses. |
Example
{
"references": ["ela-district-a"]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1389193100,
"records": 1
},
"data": {
"reference": "ela-district-a",
"description": "Content pool for ELA District A",
"name": "ELA 2015 District A",
"status": "published",
"dt_created": 2015-01-08T07:34:00Z,
"dt_updated": 2015-01-08T07:34:00Z
}
}
*/
Set Pools
Create new Item pools for the specified Item bank.
You would want to use this to create a new Item pool based on specific Items, Activities, or Items and Activities that have specific Tags.
See Using Item Pools to Create Content Snapshots for more information.
This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs
endpoint and the returned job_reference
to check the status of the job.
Endpoint | /[LTS_VERSION]/itembank/pools |
---|---|
HTTP Method | POST |
Action Type | set |
Returns | JSON object containing a job_reference that can be used against the jobs endpoint to track the completion of the (asynchronous) request. |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
pools array[object] |
A list of Item pools to create. See below for supported attributes. Maximum: 50 Item pool definitions. |
pools[].reference string |
The unique Item pool reference. |
pools[].name string |
A human readable name used to identify the Item pool. |
pools[].content object |
Configuration for Items and/or Activities to add to the Item pool. Content has to contain at least one valid entry. See below for supported attributes. |
pools[].content.item_references array[string] |
Item references to add to the pool. |
pools[].content.activity_references array[string] |
Activity references to add to the pool. |
pools[].content.tags array[TagV2|object] |
Include Items and Activities which have been assigned to specific Tags or Tag combinations to be added into the Item pool. See Understanding Tag Formats for Content Creation and Filtering for more information. There are two modes of operation for specifying Tags:
|
pools[].content.tags[].required_tags array[TagV2] |
(mandatory) A list of TagsV2 objects, in which content must be tagged with all Tags in the array. |
pools[].content.tags[].additional_tags array[TagV2] |
(optional) A list of TagsV2 objects, in which content must be tagged with at least one Tag in the array. |
pools[].content.item_tags array |
The same as tags , but only Items will be added using this Tag list.
|
pools[].content.activity_tags array |
The same as Note Items associated with the Activity will be added as normal. |
pools[].status string |
Possible values:
Default: |
pools[].overwrite boolean |
(optional) Overwrite the Item pool if the Item pool reference already exists. Default: |
pools[].ignore_empty_additional_tags boolean |
(optional) When using advanced Tag combinations, if no content is found using the Set this option to |
pools[].set_unpublished_to_published boolean |
(optional) Set all content to published when added to the Item pool. By default, unpublished content cannot be added to Item pools. You can use this to include content regardless of its publishing status. Default: |
pools[].description string |
(optional) A description of the Item pool. |
Example
{
"pools": [
{
"reference": "new_test_pool",
"name": "New test pool",
"description": "This is a test pool",
"content": {
"item_references": [
"dataapi_test_001"
],
"activity_references": [
"CCASWinter14G06AVE"
],
"tags": [
{
"type": "course",
"name" : "commoncore"
}
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1389178000,
"records": 1
},
"data": [
{
"pool_reference": "new_test_pool",
"job_reference": "987y12nflkdv"
}
]
}
*/
/*
* Advanced Tag combination example.
*
* The below Tag combinations example will add:
* 1) any content tagged with all tagnames of tagtype "course"
* 2) any content tagged with:
* (foo: bar AND baz: *) AND (qux: quux OR corge: * OR grault: garply)
*/
{
"pools": [
{
"reference": "new_test_pool",
"name": "New test pool",
"description": "This is a test pool",
"content": {
"tags": [
{
"type": "course"
// Tag name is optional
},
{
"required_tags": [
{
"type": "foo",
"name": "bar"
},
{
"type": "baz"
// Tag name is also optional in advanced Tag usage
}
],
"additional_tags": [
{
"type": "qux",
"name": "quux"
},
{
"type": "corge"
},
{
"type": "grault",
"name": "garply"
}
]
}
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1389193100,
"records": 1
},
"data": [
{
"pool_reference": "new_test_pool",
"job_reference": "54fcffa26610"
}
]
}
*/
Update Pools
Update existing Item pools to add or overwrite content.
You would want to use this to make amendments or corrections to existing Item pools.
Note Items pools are designed to be a snapshot of an Item bank. For large changes, it is highly recommended to create a new Item pool instead of modifying an existing Item pool. This reduces the risk of making unintended changes to live assessments.
See Using Item Pools to Create Content Snapshots for more information.
This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs
endpoint and the returned job_reference
to check the status of the job.
Endpoint | /[LTS_VERSION]/itembank/pools |
---|---|
HTTP Method | POST |
Action Type | update |
Returns | JSON object containing a job_reference that can be used against the jobs endpoint to track the completion of the (asynchronous) request. |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
pools array |
An array of objects should be provided, each object representing a separate Item pool. The maximum number of array elements permitted is 50. |
pools[].reference string |
Unique id of the new pool |
pools[].name string |
User-friendly name of the pool |
pools[].content object |
Information about which Items/Activities to add to the pool. Content has to contain at least one valid entry. |
pools[].content.item_references array |
Item references to add to the pool |
pools[].content.activity_references array |
Activity references to add to the pool |
pools[].content.tags array |
Simple:
Each Tag entry consists of a Tag type and a Tag name - Tag types are
mandatory
, while Tag names are
optional
.
Advanced: Each Tag entry can consist of an array of required_tags and an array of additional_tags - required_tags are mandatory, additional_tags are optional. required_tags is an array of tags (as described in simple), in which content must be tagged with every Tag in the array. additional_tags is an array of tags (as described in simple), in which content must be tagged with at least one Tag in the array. Items and Activities tagged with those Tags (or adhere to the Tag combinations) are added to the pool. See also the knowledgebase article about Tags. |
pools[].content.item_tags array |
The same as 'Tags', but only Items will be added using this Tag list. |
pools[].content.activity_tags array |
The same as 'Tags', but only Activities will be added using this Tag list. Note Items associated with the Activity will be added as normal. |
pools[].status string |
[optional] Either published or unpublished , defaults to published |
pools[].set_unpublished_to_published boolean |
[optional] Set to true to allow the update of a pool with unpublished content. By default, you are prevented from storing unpublished content in Item bank pools. Default: false. |
pools[].overwrite boolean |
[optional] If true, only the existing pool objects listed in pools[].content will be overwritten with the new state of these objects in Item bank. Default: false. |
Example
{
"pools": [
{
"reference": "new_test_pool",
"name": "Updated test pool",
"description": "This is a test pool",
"content": {
"item_references": [
"dataapi_test_001"
],
"activity_references": [
"CCASWinter14G06AVE"
],
"tags": [
{
"type": "course",
"name" : "commoncore"
}
]
}
}
]
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1440467404
},
"data": [
{
"pool_reference": "new_test_pool",
"job_reference": "8f49db43-0d54-4fc5-8154-a721b0334898"
}
]
}
*/
Upload Assets
Upload assets directly to Learnosity cloud storage in bulk.
This endpoint generates a set of pre-signed upload URLs (one per asset requested), which can then be used to upload the asset files themselves. The upload is done by sending an HTTP PUT
request to each of the signed URLs. See the section Uploading Asset Files using Signed URLs for more information.
The endpoint also returns the corresponding public URLs for retrieving the uploaded assets later on.
The endpoint infers the Content-Type for assets based on the filename extension (e.g. image/jpeg
for .jpg
, image/png
for .png
). There is support for overriding the inferred type, or specifying it for files where it cannot be inferred from the filename extension.
Endpoint | /[LTS_VERSION]/itembank/upload/assets |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
items array |
Array of objects
|
subkeys array |
An array of strings, where each string is a "key" representing the desired name for a particular asset. This key is used in the path of the asset's public URL.
|
subkey_types object |
(optional) An object with string keys and string values, where each object key corresponds to an entry in the
Every key in the A key may be omitted if the default Content-Type for a file's extension is what is desired. |
organisation_id integer |
Specifies the Item bank for uploading assets. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Response
An array of objects, with each object representing one of the assets to be uploaded. Each object contains the following keys:
upload
- the upload URL to which to make aPUT
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 theContent-Type
header in thePUT
request to the upload URL.
Uploading Asset Files using Signed URLs
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 appropriatecontent_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"
}
]
}
*/
Get Local Device Assessment Package
Download all content in assessment from your Item bank for offline use in a local device. The content from this endpoint is used in the Learnosity local device assessment app.
Note: This is an enterprise product. Contact Learnosity Support for more information.
This endpoint will create a job to be completed asynchronously which can be polled for, using the GET jobs
endpoint and the returned job_reference
to check the status of the job.
Endpoint | /[LTS_VERSION]/itembank/offlinepackage |
---|---|
HTTP Method | POST |
Action Type | get |
Returns | JSON object containing a The jobs endpoint (with |
Parameter | Description |
organisation_id integer |
Specifies the Item bank to retrieve content from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
activity_references array[string] |
A list of Activity references to include in the local device package. Default: 1000 Activity references. |
items array[object] |
A list of ItemObjects to be packaged. |
item_references array[string] Deprecated |
A list of Item references to be packaged. Maximum: 1000 references. |
base_directory string |
(optional) Specify the base directory for all content and assets. Default: |
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"
}
]
}
*/
Get Workflows
Retrieve all of the Item review workflows available for the specified Item bank.
You would want to use this to inspect the all of the rules applied to a specific workflow.
Endpoint | /[LTS_VERSION]/itembank/workflows |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id integer |
(optional) Specifies the Item bank to retrieve workflows from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
limit integer |
(optional) Restricts the number of records returned. Default: 50 records. |
next string |
(optional) A token used to request the next page of results. After making an initial request, if it would produce a result set larger than the specified |
references array |
(optional) Include specific workflow references. Maximum: 1000 workflow references.
|
Example
{
"request": {
"references": [
"Default workflow"
]
}
}
/* Example Response
{
"meta": {
"status": true,
"timestamp": 1583988357,
"records": 1
},
"data": [
{
"reference": "Default workflow",
"initial_state_reference": "DRAFT",
"final_state_reference": "APPROVED",
"description": "Default workflow description",
"workflow_states": [
{
"reference": "APPROVED",
"description": "APPROVED STATE",
"label": "APPROVED",
"workflow_transitions": [
{
"label": "APPROVED TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
}
]
},
{
"reference": "BLOCKED",
"description": "BLOCKED STATE",
"label": "BLOCKED",
"workflow_transitions": [
{
"label": "BLOCKED TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"label": "BLOCKED TO REWORK",
"to_state_label": "REWORK",
"to_state_reference": "REWORK",
"display_order": 2
},
{
"label": "BLOCKED TO DRAFT",
"to_state_label": "DRAFT",
"to_state_reference": "DRAFT",
"display_order": 3
}
]
},
{
"reference": "DRAFT",
"description": "DRAFT STATE",
"label": "Draft",
"workflow_transitions": [
{
"label": "DRAFT TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"label": "DRAFT TO BLOCKED",
"to_state_label": "BLOCKED",
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
},
{
"reference": "REVIEW",
"description": "REVIEW STATE",
"label": "REVIEW",
"workflow_transitions": [
{
"label": "REVIEW TO APPROVED",
"to_state_label": "APPROVED",
"to_state_reference": "APPROVED",
"display_order": 1
},
{
"label": "REVIEW TO REWORK",
"to_state_label": "REWORK",
"to_state_reference": "REWORK",
"display_order": 2
}
]
},
{
"reference": "REWORK",
"description": "REWORK STATE",
"label": "REWORK",
"workflow_transitions": [
{
"label": "REWORK TO REVIEW",
"to_state_label": "REVIEW",
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"label": "REWORK TO BLOCKED",
"to_state_label": "BLOCKED",
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
}
]
}
]
}
*/
Set Workflows
Create a new Item review workflow for the specified Item bank.
You would want to use this to set up a new Item review workflow so that your content creators can collaborate as desired.
Endpoint | /[LTS_VERSION]/itembank/workflows |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
organisation_id integer |
(optional) Specifies the Item bank to update. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
workflows array[object] |
(mandatory) A list of the workflows to create. Maximum: 50 workflows. See below for supported attributes. |
workflows[].reference string |
(mandatory) The unique reference for the workflow. Once created, this workflow reference can be used in the Author API initialization options to enable the workflow states. Maximum: 150 ASCII characters. Note: double quotes, single quotes, and accent characters are not allowed. |
workflows[].description string |
(optional) The description of the workflow. Maximum: 1000 characters. |
workflows[].initial_state_reference string |
(mandatory) The starting state of the workflow. This reference must match one of the state references provided in Maximum: 150 characters. Note: The reference is case sensitive. |
workflows[].final_state_reference string |
(mandatory) The ending state of the workflow. This reference must match one of the state references provided in Maximum: 150 characters. Note: The reference is case sensitive. |
workflows[].workflow_states array[object] |
(mandatory) A list of each separate state for the workflow. See below for supported attributes. |
workflows[].workflow_states[].reference string |
(mandatory) The unique reference for the state. Maximum: 150 characters. Note: The reference is case sensitive. |
workflows[].workflow_states[].description string |
(optional) The description of the state. Maximum: 1000 characters. |
workflows[].workflow_states[].label string |
(mandatory) A human readable label for the state shown in the user interface. Maximum: 150 characters. |
workflows[].workflow_states[]. workflow_transitions array[object] |
(mandatory) Define all the states for the workflow. See below for supported attributes to define each state. |
workflows[].workflow_states[]. workflow_transitions[].to_state_reference string |
(mandatory) The next state reference that the current state can progress to. This reference must match one of the state references provided in Maximum: 150 characters. Note: The reference is case sensitive. |
workflows[].workflow_states[]. workflow_transitions[].display_order integer |
(mandatory) Set the display order for this state. The state transitions are numerically sorted in the user interface, from smallest to largest, where the smallest appears on top. For example, when you have five states numbered from one to five, one will appear first in the list of states. |
Example
{
"request": {
"workflows": [
{
"reference": "Default workflow",
"initial_state_reference": "DRAFT",
"final_state_reference": "APPROVED",
"description": "Default workflow description TEST1",
"workflow_states": [
{
"reference": "DRAFT",
"description": "DRAFT STATE",
"label": "DRAFT",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
},
{
"reference": "BLOCKED",
"description": "BLOCKED STATE",
"label": "BLOCKED",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"to_state_reference": "REWORK",
"display_order": 2
},
{
"to_state_reference": "DRAFT",
"display_order": 3
}
]
},
{
"reference": "REWORK",
"description": "REWORK STATE",
"label": "REWORK",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
},
{
"to_state_reference": "BLOCKED",
"display_order": 2
}
]
},
{
"reference": "REVIEW",
"description": "REVIEW STATE",
"label": "REVIEW",
"workflow_transitions": [
{
"to_state_reference": "APPROVED",
"display_order": 1
},
{
"to_state_reference": "REWORK",
"display_order": 2
}
]
},
{
"reference": "APPROVED",
"description": "APPROVED STATE",
"label": "APPROVED",
"workflow_transitions": [
{
"to_state_reference": "REVIEW",
"display_order": 1
}
]
}
]
}
]
}
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1583990495
},
"data": []
}
*/
Get Activity Player Templates
Retrieve all Activity assessment player templates for a specific Item bank.
You would want to use this to retrieve all assessment player templates to review the layout, settings, and label bundles which have been configured.
Endpoint | /[LTS_VERSION]/itembank/playertemplates |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id integer |
(optional) Specifies the Item bank to retrieve Activity player templates from. The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console. Default: the primary Item bank associated with the API consumer. |
Example
// No parameters applicable. The endpoint always returns all Activity player templates.
{}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1633504859,
"records": 1
},
"data": [
{
"name": "Test Player Template",
"reference": "980fe27e-b0e4-4b18-bb32-f036921ca1ea",
"json": {
"regions": {
"top-left": [
{
"type": "title_element"
},
{
"type": "save_button"
}
],
"top-right": [
{
"type": "pause_button",
"position": "right"
},
{
"type": "timer_element"
},
{
"type": "reading_timer_element"
},
{
"type": "itemcount_element"
}
],
"right": [
{
"type": "verticaltoc_element"
},
{
"type": "fullscreen_button"
},
{
"type": "reviewscreen_button"
},
{
"type": "resource_button"
},
{
"type": "accessibility_button"
},
{
"type": "calculator_button"
},
{
"type": "flagitem_button"
},
{
"type": "notepad_button"
},
{
"type": "stickynote_add_button"
},
{
"type": "stickynote_visibility_button"
},
{
"type": "drawing_mode_button"
},
{
"type": "drawing_visibility_button"
}
],
"bottom-right": [
{
"type": "next_button"
},
{
"type": "previous_button"
}
],
"items": [
{
"type": "slider_element",
"scrollable_option": false
}
]
},
"labelBundle": {
"actionsave": "Commit"
},
"custom_data": {
"custom_key": "some_value"
}
}
}
]
}
*/
Get Tags Deprecated
This has been superseded by get /itembank/tagging/tags.
Endpoint | /[LTS_VERSION]/itembank/tags |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id v2019.2.LTS or later integer |
Returns content from the Item bank with the supplied ID. The consumer making the request will need to have access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console. |
item_pool_id string |
Returns content from an Item pool instead of the Item bank |
tags array |
Array of Tag strings |
types array |
Array of Tag type strings |
Example
{
"types": ["course", "subject"],
"tags": ["English", "Maths"],
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1389193100
},
"data": {
"subject": [
"English",
"Maths"
]
}
}
*/
Set Tags Deprecated
This has been superseded by set /itembank/tagging/tags.
Endpoint | /[LTS_VERSION]/itembank/tags |
---|---|
HTTP Method | POST |
Action Type | set |
Parameter | Description |
organisation_id v2019.2.LTS or later integer |
Sets content to the Item bank with the supplied ID. The consumer making the request will need to have access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console. |
tags object |
TagsV2 object
The maximum number of distinct Tag types permitted in the TagsV2 object is 1000. |
Example
{
"tags": {
"course": [
"Common Core"
],
"subject": [
"maths",
"english"
]
}
}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1396235761
},
"data": []
}
*/
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 | /[LTS_VERSION]/itembank/activities/templates |
---|---|
HTTP Method | POST |
Action Type | get |
Parameter | Description |
organisation_id v2019.2.LTS or later integer |
Returns content from the Item bank with the supplied ID. The consumer making the request will need to have access to the Item bank. This access can be ensured via API consumers configuration in the Learnosity Console. |
Example
// No parameters applicable. The endpoint always returns all Activity templates.
{}
/* Example Response:
{
"meta": {
"status": true,
"timestamp": 1408491907,
"records": 3
},
"data": [
{
"reference": "BASETEMPLATE_1",
"data": {
"config": {
"ui_style": "main",
"navigation": {
"show_title": true,
"show_itemcount": true,
"show_fullscreencontrol": false,
"toc": true,
"auto_save": {
"save_interval_duration": 300
}
}
}
},
"description": "base_1",
"status": "archived"
},
{
"reference": "BASETEMPLATE_2",
"data": {
"config": {
"ui_style": "main",
"navigation": {
"show_title": true,
"toc": true
},
"title": "base_2 title",
"subtitle": "base_2 subtitle"
}
},
"description": "base_2",
"status": "published"
},
{
"reference": "BASETEMPLATE_3",
"data": {
"config": {
"ui_style": "horizontal",
"navigation": {
"show_title": false,
"toc": false
},
"title": "base_3 title",
"subtitle": "base_3 subtitle"
}
},
"description": "base_3",
"status": "published"
}
]
}
*/