Questions endpoint

Manage Questions in your Item bank.

Endpoints:

Get Questions
Set Questions
Duplicate Questions

Usage

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

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

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

https://data.learnosity.com/v2025.2.LTS/itembank/questions

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

Request body parameters

Body content type: application/json

include object

(optional) Properties to be returned in the response.

The following properties are supported.
- questions array[string]
  
  (optional) Question properties to be returned in the response.
  
  Possible values
  - dt_created
  - dt_updated
organisation_id integer

Specifies the Item bank to retrieve Questions from.

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

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

Return content from an Item pool instead of the Item bank.

item_references array[string]

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

Example

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

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

Maximum entries: 1000

limit integer

Restricts the number of records returned.

Default: 50
maxtime integer string

Controls the latest timestamp used to filter results, based on the value specified in the sort_field parameter.

You would want to use this so that you can limit results to only those created or updated before a specific date or time.

Accepts a UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. By default, results are sorted in descending order, but this can be changed using the sort parameter.
mintime integer string

Controls the earliest timestamp used to filter results, based on the value specified in the sort_field parameter.

You would want to use this so that you can limit results to only those created or updated after a specific date or time.

Accepts a UTC Unix timestamp or datetime string (in ISO 8601 format) to get results from. By default, results are sorted in descending order, but this can be changed using the sort parameter.
next string

A token used to request the next page of results.

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

A list of Question references.

Maximum entries: 1000
sort string

Determines response sorting by ascending or descending order.

Default: desc

Possible values
- asc
- desc
sort_field string

Specifies the time field to sort the results by.

Default: created

Possible values
- created
- updated
types array[string]

Specifies the Question types to retrieve.

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

Request body example

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

Responses

Response example

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

Request body parameters

Body content type: application/json

meta object

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

The following properties are supported.
- user object
  
  (optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the new Questions, and will be shown in Learnosity Author Site when viewing the history of changes on a Question.
  
  Default: Manual User/Data GUI
  
  The following properties are supported.
  - 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 new or modified Questions.
    
    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 Questions.
    
    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 Questions.
    
    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.
questions array[object]

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

Maximum entries: 50

The following properties are supported.
- type string
  
  Specifies the Question type.
  
  See Question & Feature Codes for Data API filtering for a full list of Question type codes.
- reference string
  
  A unique reference for the Question.
  
  Must contain only letters, numbers, underscores, or dashes.
  
  Maximum length: 150
- 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.

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

Responses

Response example

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

Request body parameters

Body content type: application/json

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

An array of Item references for which Questions should be duplicated.
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 Questions created in this request.

The following properties are supported.
- user object
  
  (optional) Details of the user issuing this request. The user details are recorded in the audit trail for each of the created Questions, and will be shown in Learnosity Author Site when viewing the history of changes on the Questions.
  
  Default: Manual User/Data GUI
  
  The following properties are supported.
  - 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 Questions.
    
    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 Questions.
    
    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 Questions.
    
    Maximum length: 255

Request body example

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

Responses

Response example

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

Questions endpoint

Usage

Get Questions

Request body parameters

Request body example

Responses

Response example

Set Questions

Request body parameters

Request body example

Responses

Response example

Duplicate Questions

Request body parameters

Request body example

Responses

Response example

Related articles