Items endpoint

Manage Items in your Item bank.

Endpoints:

Get Items
Set Items
Duplicate Items

Usage

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

https://data.learnosity.com/{LTS_VERSION}/{endpoint}

For example, to use the v2025.1.LTS version and the itembank/items endpoint, you would create a request like so:

https://data.learnosity.com/v2025.1.LTS/itembank/items

Important Data API is not a REST API. All requests must use the POST method with the action request body parameter specifying the operation to use. The Learnosity SDK must be used to make requests to Data API.

Note Data API usage is subject to rate limits.

Getting Started with the Data API
See Release Cadence and Version Lifecycle for more information on available LTS versions.

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"`

Request body parameters

Body content type: application/json

authoring_workflow object

(optional) Includes Items with a specific workflow reference and its states.
- reference string
  
  Includes Items by the workflow reference they belong to.
  
  Important The workflow reference is mandatory if the authoring_workflow is part of the request.
- states array[string]
  
  (optional) Includes Items by their workflow states.
  
  By default, returns all Items regardless of their workflow state.
  
  To retrieve all Items which do not have any workflow states applied, you can set this option to ["Unassigned"].
created_by array[string]

Includes Items with a specific user IDs that created the Item.
include object

(optional) The Item properties to be returned in the response.
- items array[string]
  
  (optional) Item properties to be returned in the response.
  
  Note The authoring_workflow will be null for Items in the "Unassigned" workflow state that are returned in the response.
  
  For the "dynamic_content_data" option, see What is Dynamic Content? for more information.
  
  For the "authoring_workflow" option, see Item Review Workflow for more information.
  
  Possible values
  - adaptive
  - dt_created
  - dt_updated
  - created_by
  - last_updated_by
  - max_score
  - dynamic_content_data
  - authoring_workflow
item_pool_id string

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

Restricts the number of records returned.

Maximum: 50
maxtime integer string

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

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

A token used to request the next page of results.

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

(optional) Includes Items containing a specific Question reference or type.
- references array[string]
  
  Includes Items that contain at least one of the specified Question references.
  
  Maximum entries: 1000
- types array[string]
  
  Includes Items that contain any specified Question or Feature types, for example, mcq, clozeassociation, sharedpassage, etc.
  
  See Question & Feature type codes for a full list.
references array[string]

Includes specific Item references in the results.

Maximum entries: 1000
scoring_type array[string]

Includes Items by their scoring types.

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

Possible values
- per-question
- per-dichotomous
- dependent
sort string

Determines response sorting by ascending or descending order.

Default: desc

Possible values
- asc
- desc
sort_field string

The field to sort the results by.

Default: created

Possible values
- created
- updated
- reference
- title
status array[string]

Includes Items by their statuses.

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

Possible values
- published
- unpublished
- archived
tags array[object]

Includes Items with specified Tags. Each element must be a TagsV2 Object or TagSearchByType Object.

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

Specify more complex search queries based on Tags, including optional or negative criteria. At least one of the following object keys must be present:
- "all"
- "either"
- "none"
See AdvancedTagSearchParams (Data API) for more information.
organisation_id integer

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

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

Request body 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"]
    }
}

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

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

Responses

Response example

// Find Items by Tags 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 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 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"`

Request body parameters

Body content type: application/json

items array[object]

A list of Item definition objects where each object represents a separate Item.

Maximum entries: 50
- adaptive object
  
  (optional) The adaptive data to be used in the assessments as per Adaptive Assessments.
  - difficulty integer
    
    (optional) Sets the adaptive difficulty value of the Item.
    
    See Adaptive Assessments for more information.
- authoring_workflow object
  
  (optional) Definition for the Item workflow data.
  - reference string
    
    Reference of the workflow the Item should use.
  - state string
    
    Workflow state that should be assigned to the Item.
- definition object
  
  The Item layout definition.
  
  See the Item Definition for more information.
- description string
  
  The description of the Item.
  
  This field only appears within the Learnosity Author Site or Author API for authors.
- dynamic_content_data object
  
  Data for dynamic content Items.
  
  See What Is Dynamic Content? for more information.
- features array[string]
  
  A list of Feature references to be included in the Item.
- metadata object
  
  The general metadata attached to the Item.
  - 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 is permitted.
  - scoring_type string
    
    The scoring method for the Item.
    
    See Per Question, Dichotomous, And Dependent (EBSR) Item Scoring With Examples for more information.
    
    Possible values
    - per-question
    - per-dichotomous
    - dependent
- new_reference string
  
  (optional) Update an Item's reference with a new value.
  
  When items[].reference is provided and this attribute is specified, the existing Item reference will be updated to this value.
- note string
  
  General text field for authors to leave notes. These notes are not shown to the learner.
- questions array[object]
  
  A list of Questions to include in the Item.
  - reference string
    
    The individual Question reference.
    
    Must contain only letters, numbers, underscores, or dashes.
- reference string
  
  The reference for the Item.
  
  Note Double quotes, single quotes, and accent characters are not allowed.
  
  Maximum: 150 ASCII characters.
  
  Maximum length: 150
- 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.
- status string
  
  The workflow status of the Item.
  
  Note the status must be "published" to be used in assessments.
  
  Default: unpublished
  
  Possible values
  - published
  - unpublished
  - archived
- tags array[object]
  
  A list of TagsV2 objects to apply to the Item.
- title string
  
  A human readable title used to identify an Item which can be seen in the Author API and Learnosity Author Site.
  
  Maximum length: 150
meta object

(optional) A metadata object which will be applied to all Items created in this request.
- user object
  
  (optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item.
  
  Default: Manual User/Data GUI
  - id string
    
    The ID of the user issuing this request.
    
    Important If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.
    
    Note The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.
    
    The user ID can also be passed to GET /itembank/items to filter by created_by.
    
    Maximum length: 50
  - 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 length: 50
  - 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 length: 50
  - 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 length: 255
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.

Request body 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": {}
        }
    ]
}

Responses

Response example

{
    "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"`

Request body parameters

Body content type: application/json

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[object]

A list of Item definitions where each object represents an Item to be duplicated. All Questions within the specified Items are also duplicated.

Maximum entries: 50
- reference string
  
  Specifies the reference of an Item you want to duplicate.
- new_reference string
  
  (optional) The new reference of the duplicated Item.
  
  If this is not specified, a reference for the duplicated Item will be automatically generated.
  
  Note The new reference cannot already exist.
duplicate_shared_passages boolean

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

Default: false
meta object

(optional) A metadata object which will be applied to all Items created in this request.
- user object
  
  (optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the created Items, and will be shown in Learnosity Author Site when viewing the history of changes on an Item.
  
  Default: Manual User/Data GUI
  - id string
    
    The ID of the user issuing this request.
    
    Important If the ID provided does not exist, a new user will be created. If the ID provided already exists, then all the attributes provided (meta.user.firstname, meta.user.lastname, or meta.user.email) will overwrite the existing attributes.
    
    Note The user ID value is shown in the Learnosity Author Site audit trail if both meta.user.firstname and meta.user.lastname are not provided.
    
    Maximum length: 50
  - 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 length: 50
  - 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 length: 50
  - 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 length: 255

Request body example

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

Responses

Response example

{
    "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
            }
        }
    }
}

Items endpoint

Usage

Get Items

Request body parameters

Request body example

Responses

Response example

Set Items

Request body parameters

Request body example

Responses

Response example

Duplicate Items

Request body parameters

Request body example

Responses

Response example

Related articles