Activities endpoint

Manage Activities in your Item bank.

Endpoints:

• Get Activities
• Set Activities
• Duplicate Activites

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.

Related articles:

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

Retrieve Activities from your Item bank.

You would want to use this to retrieve and load your Activities into your own application, for example.

Request body parameters

Body content type: application/json

• include object

  (optional) Properties to be returned in the response.

• include.activities array[string]

  (optional) Activity properties to be returned in the response. The `dt_created` represents the date time created and `dt_updated` represents the date time updated.

  Possible values

  • created_by
  • dt_created
  • dt_updated
  • last_updated_by
  • metadata
  • title

• 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

  Includes Activities with a combination of the specified Item references.

  At least one of the attributes must be present and you can use both together if required. When both "all" and "either" are defined, all of the Item references in "all" must be found and at least one of the Item references in "either" must be found, or no results will be returned.

  Note Only applies to published Items belonging to the same Item bank as the Activity.

  Note Not supported for Item pools.

  • all array[string]

    Activities must contain all of the listed Item references.

  • either array[string]

    Activities must contain at least one of the listed Item references.

• limit integer

  Restricts the number of records returned.

  Default: 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) 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.

• references array[string]

  The Activity references (called activity_template_id when you initialize an assessment) to include.

  Maximum entries: 1000

• sort string

  Determines response sorting.

  Default: desc

  Possible values

  • asc
  • desc

• sort_field string

  Specifies the field to sort the results by with either the creation time or the last time updated.

  Default: created

  Possible values

  • created
  • updated

• status array[string]

  (optional) Includes Activities by their statuses.

  When no option is set, all Items are returned which includes all published, unpublished, and archived Items.

  Default: []

  Possible values

  • published
  • unpublished
  • archived

• tags array[TagsV2] object

  Includes Activities with specified Tags. A list of TagsV2 objects can be specified or a TagSearchByType object definition.

  When searching using multiple Tags of different types, specify the advanced_tags option with the "either" value. See below for more information.

• advanced_tags object

  Includes Activities using one of the following tagging conditions.

  At least one of the above keys must be present.

  See Understanding Tag Formats for Content Creation and Filtering for more information.

  • all array[TagsV2]

    Activities must contain all of the listed Tags.

  • either array[TagsV2]

    Activities must contain at least one of the listed Tags.

  • none array[TagsV2]

    Activities must not contain any of the listed Tags.

Request body example

// Get Activities with specific Items
{
    "item_references": {
        "all": [ "item_reference_1", "item_reference_2"],
        "either": [ "item_reference_3", "item_reference_4"]
    }
    // ...
}

// Get Activities with specific Tags
{
    "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 parameters.
    // ...
}

Responses

Response example

// Get Activities with specific Items
{
    "meta": {
        "status":true,
        "timestamp":1389192595
    },
    "data": [
        {
            "reference":"activity_ref_1",
            "description":"",
            "data": {
                "activity_id": "1344151",
                "name": "Activity Ref 1",
                "rendering_type": "assess",
                "state": "initial",
                "type": "submit_practice",
                "items":
                    {
                        "reference": "item_reference_1",
                        "id": "item_reference_1",
                        "organisation_id": 1,
                    },
                    {
                        "reference": "item_reference_2",
                        "id": "item_reference_2",
                        "organisation_id": 1,
                    },
                    {
                        "reference": "item_reference_4",
                        "id": "item_reference_4",
                        "organisation_id": 1,
                    }
                ],
                "config": {
                    "navigation": {
                        "show_next": true
            },
            "status": "published",
            "tags": {
                "test": [
                    "tag"
                ]
            },
            "dt_created": "2024-03-26 05:32:15"
        }
    ]
}

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

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.

Request body parameters

Body content type: application/json

• activities array[object]

  An array of objects where each represents a separate Activity.

  Maximum entries: 50

  • base_template_id string Deprecated

    No longer supported.

    The base template reference to be applied on the Activity.

  • data object

    The JSON representation of an Activity. All supported Activity properties can be found in the Items API documentation.

    Default: { "rendering_type": "assess" }

    • items array[object]

      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 config object, such as the intro_item, outro_item, and resource_item referenced under the config.navigation property.

    • config object

      The initialization options for the Activity.

      See the Items API documentation for supported options.

    • sections array[object]

      Define sections for the Activity. Sections allow 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.

  • description string

    A description for the Activity, visible only to authors via the Author API and Learnosity Author Site.

  • reference string

    The reference for the Activity.

    Maximum: 150 ASCII characters

    Note Double quotes, single quotes, and accent characters are not allowed.

    Maximum length: 150

  • status string

    The status of the Activity.

    See Changing The Activity Status In The Activity Editor for more information.

    Note The Activity must be set to "published" so that it can be used in assessments.

    Default: published

  • tags array[TagsV2]

    A list of Tags to assign to the Activity.

    See TagsV2 for more information.

  • 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.

  • 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: 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 new or modified Activities.

      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 Activities.

      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 Activities.

      Maximum length: 255

• 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.

Request body example

{
    "activities": [
        {
            "reference": "ela-unit-1",
            "data": {
                "items": [
                    "ela_item_1",
                    "ela_item_2"
                ],
                "config": {
                    "regions": "main"
                },
                "rendering_type": "assess"
            },
            "tags": [
                {
                    "type": "subject",
                    "name": "math"
                }
            ]
        }
    ]
}

Responses

Response example

{
    "meta": {
        "status": true
    },
    "data": []
}

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.

Request body parameters

Body content type: application/json

• 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 consumer's 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 entries: 10

  • reference string

    The reference of an Activity you want to duplicate.

  • new_reference string

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

  Controls 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 duplicated Activities 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 or modified Activities, and will be shown in Learnosity Author Site when viewing the history of changes on an Activity.

    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 Activities.

      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 Activities.

      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 Activities.

      Maximum length: 255

Request body example

{
    "activities": [
        {
            "reference": "ACTIVITY_7",
            "new_reference": "DuplicatedActivity"
        }
    ]
}

Responses

A JSON object containing a job_reference that can be submitted to the jobs endpoint to track the completion of the asynchronous request.

Response example

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