Tags endpoint

Manage Tags in your Item bank.

Endpoints:

• Get Tags
• Set Tags
• Get Tags - Deprecated
• Set Tags - Deprecated

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 Tags from your Item bank.

You would want to use this to retrieve specific Tags for use in your own application, for example.

Request body parameters

Body content type: application/json

• organisation_id integer

  Specifies the Item bank to retrieve Tags.

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

• limit integer

  Restricts the number of records returned.

  Maximum: 50

• names array[string]

  A list of Tag names to retrieve.

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

• sort string

  Determines response sorting by ascending or descending order.

  Default: desc

  Possible values

  • asc
  • desc

• sort_field string

  Specifies the field to sort the results by.

  Possible values:

  • "sort_key": sort by Tag type, then by the Tags' sort_key value (as defined in the Author Site), and then finally by Tag name.
  • "created": sort by time created.
  • "updated": sort by time updated.

  Default: updated

• types array[string]

  Includes only the specified Tag type(s).

  This is optional unless the sort_field is set to "sort_key", in which case at least one Tag type must be provided.

Request body example

{
    "types": [
        "course",
        "subject"
    ],
    "names": [
        "Math",
        "Advanced Math",
        "English"
    ],
    "sort_field": "updated",
    "limit": 2
}

Responses

Response example

{
    "meta": {
        "status": true,
        "timestamp": 1389193100,
        "records": 2,
        "next": "138919500.781"
    },
    "data": [
        {
            "type": "course",
            "name": "Math",
            "description": "Elementary math"
        },
        {
            "type": "course",
            "name": "English",
            "description": "English reading, writing, literature"
        }
    ]
}

Creates or overwrites Tags in your Item bank.

You would want to use this to bulk create new Tags to assign to Items and Activities.

Important Existing Tags with the same type and name will be overwritten with the new values.

Request body parameters

Body content type: application/json

• meta object

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

  • user object

    (optional) Contains user details of the user issuing the create or update operation in this request. The user details are recorded in the audit trail for each of the new or modified Tags.

    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 or updated 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 created or updated 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 created or updated 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.

• tags array[object]

  An array of TagsV2 objects should be provided, each object representing a separate Tag type or Tag combination.

  Maximum entries: 1000

  • description string

    A longer description for the Tag.

    This may be provided as null which will unset the value. When this is omitted, the description field will remain unchanged.

  • name string

    The Tag name.

  • sort_key integer

    The display order of the Tag as set up in the Author Site.

  • type string

    The Tag type.

Request body example

{
    "tags": [
        {
            "type": "course",
            "name": "Common Core",
            "sort_key": 1,
            "description": "common core subjects"
        },
        {
            "type": "subject",
            "name": "Maths",
            "sort_key": 3,
            "description": "mathematics"
        },
        {
            "type": "subject",
            "name": "English",
            "sort_key": 2,
            "description": "English literature and comprehension"
        }
    ]
}

Responses

Response example

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

This has been superseded by GET /itembank/tagging/tags.

Request body parameters

Body content type: application/json

• organisation_id integer

  Specifies the Item bank to retrieve Tags.

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

• tags array[string]

  A list of Tag names to retrieve.

• types array[string]

  Includes only the specified Tag type(s).

Request body example

{
    "types": ["course", "subject"],
    "tags": ["English", "Maths"],
}

Responses

Response example

{
    "meta": {
        "status": true,
        "timestamp": 1389193100
    },
    "data": {
        "subject": [
            "English",
            "Maths"
        ]
    }
}

This has been superseded by SET /itembank/tagging/tags.

Request body parameters

Body content type: application/json

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

• tags object

  A TagsV2 object. The maximum number of distinct Tag types permitted in the TagsV2 object is 1000.

Request body example

{
    "tags": {
        "course": [
            "Common Core"
        ],
        "subject": [
            "maths",
            "english"
        ]
    }
}

Responses

Response example

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