Item Tags endpoint

Manage Tag associations with Items in your Item bank.

Endpoints:

• Set Items Tags
• Append Items Tags

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.

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.

Request body parameters

Body content type: application/json

• items array[object]

  A list of Item or Tag definition objects.

  Maximum: 50 Items or Tags.

  Maximum entries: 50

  • 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

  • tags array[TagsV2]

    A list of TagsV2 objects to assign to the Item.

• meta object

  (optional) A metadata object which will be applied to all Items 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 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 affected Items or Tags.

      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 affected Items or Tags.

      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 affected Items or Tags.

      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": "item1",
            "tags": {
                "demo-tagtype-1": [
                    "tag1",
                    "tag2"
                ],
                "demo-tagtype-2": [
                    "tag3"
                ]
            }
        }
    ]
}

Responses

Response example

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

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.

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

  • 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

  • tags array[TagsV2]

    A list of TagsV2 objects to assign to the Item.

• meta object

  (optional) A metadata object which will be applied to all Items 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 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 affected Items or Tags.

      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 affected Items or Tags.

      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 affected Items or Tags.

      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": "item1",
            "tags": {
                "demo-tagtype-1": [
                    "tag1",
                    "tag2"
                ],
                "demo-tagtype-2": [
                    "tag3"
                ]
            }
        }
    ]
}

Responses

Response example

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