/getNextItems

Get next Items

Learnosity will call this endpoint on your self-hosted adaptive service to get the next Item(s) for a session. This same endpoint is also called when the adaptive session is first initialized, to retrieve the first Item(s). In this case, the current_items array will be present and empty.

HTTP method: POST

Request Body

Details of the session for which the new Items are requested.

Properties marked with are mandatory.

Content type: "application/json"

• api_version string

  The version number of this API. Used to identify the format of the request payload and the format expected in the response.

  Only valid, and required, at the root level of the request.

  Example: v1.0.1

• request_uuid string (uuid)

  A unique identifier for the client's request, for tracing purposes. Useful for debugging and other investigations, as the identifier is shown to the client on error.

  Only valid at the root level of the request

  Example: D32158D4-EB10-4D75-AC72-BA7292383D49

• session_id string (uuid)

  The session ID, used to uniquely identify a user session and to group subsequent requests within the same assessment.

  Example: E439F6D7-15E4-4EBF-912F-EAA7CDB8171B

• activity_id string (uuid)

  The Activity ID, used to group sessions which are using the same assessment.

  Example: B44D81BE-BCE9-48B1-8A62-89E7BF1C772F

• user_id string (uuid)

  The user ID, used to uniquely identify a given user (learner) across sessions.

  Example: CCDD021C-6F96-41D0-96EB-406D564B0DD3

• adaptive_activity object

  The adaptive initialization option object or Item Bank Activity Template. This data is static for a given adaptive session, and will always contain the same data each time that session makes a call to your adaptive back end.

  • type string

    The type of adaptive engine to use with Items API. In this instance, only selfhosted is allowed.

    Example: selfhosted

  • selfhosted_version_major integer

    The major version of the self-hosted adaptive API supported by the adaptive back end at engine_url.

    Example: 1

  • engine_url string (url)

    The base URL (with no trailing slash) of the endpoint implementing this API. This instructs Items API about where to send the /getNextItems requests.

    If unspecified, Items API will use the preconfigured URL for the Learnosity API consumer.

    Example: https://adaptive.example.com/v1/adaptive

  • token_url string (url)

    The URL of the endpoint offering an OAuth2 token from pre-shared client credentials.

    If unspecified, Items API will use /oauth2/token on the base URL of the engine.

    Example: https://authentication.example.com/oauth/adaptive/getToken

  • custom_config object

    Configuration specific to your adaptive backend. This should contain any configuration required by your algorithm to deliver the session.

    Opaque to Learnosity.

    Example:

    {
                                        "item_pool_id": "MATH-2018"
                                    }

  • required_tags array

    Only Items matching these Tags from the Item Bank will be considered for presentation to the user.

    Note: this is also used to select Items for automatic inclusion in Item pools alongside the Activity.

    Example:

    [
                                        {
                                            "type": "Grade",
                                            "name": "6"
                                        },
                                        {
                                            "type": "Domain",
                                            "name": "Domain3"
                                        },
                                        {
                                            "type": "Domain",
                                            "name": "Domain4"
                                        }
                                    ]

• current_items array

  All the Items already seen in the session. At the beginning of a session, the array should be present and empty.

  Note: it is possible for Items to be removed from a session if a user resumes from an earlier save point.

  • reference string

    Example: item-abc-123

  • organisation_id integer

    The organisation ID of the Item bank.

    Example: 1

  • item_pool_id string

    The reference of the Item pool.

    Example: MATH-2024

  • score number (float)

    Example: 0.5

  • max_score number (float)

    Example: 1

• custom_state object

  Container for an optional custom state, persisted by Learnosity. The value provided here is the custom_state data currently persisted for this session. This can be set via the custom_state parameter of the most recent /getNextItems payload.

Response

A response payload containing a list of one or more Items that should be shown to the learner next.

HTTP status code: 200

Content type: "application/json"

• session_id string (uuid)

  The session ID, used to uniquely identify a user session and to group subsequent requests within the same assessment.

  Example: E439F6D7-15E4-4EBF-912F-EAA7CDB8171B

• next_items array

  The next Items to be added to the session.

  • reference string

    Example: item-abc-123

• is_last_items boolean

  Instructs Items API to terminate the session after these Items are completed. Defaults to false.

• custom_state object

  Container for an optional custom state, persisted by Learnosity. The provided value will overwrite the custom_state data currently persisted for this session. This data will be sent in the next request to /getNextItems via the custom_state parameter.

  Opaque to Learnosity.