Pools - Endpoints - Data API

Item Pools endpoint

Manage your Item Pools.

See Using Item Pools to Create Content Snapshots for more information.

Endpoints:

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:

Get Pools

Retrieve a list of Item pools for the specified Item bank.

You would want to use this to see all available Item pools for your Item bank and retrieve content from the desired Item pool.

See Using Item Pools to Create Content Snapshots for more information.

Endpoint /{LTS_VERSION}/itembank/pools
HTTP method POST
Action type "get"

Request body parameters

Body content type: application/json

  • organisation_id integer

    Specifies the Item bank to retrieve Item pools 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.

  • limit integer

    Restricts the number of records returned.

    Maximum: 50

  • 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 Item pool references to retrieve.

  • 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

  • status array[string]

    Includes Item pools by their statuses. By default, all statuses are included.

    Possible values

    • published
    • unpublished
    • pending
    • halted

Request body example

{
    "references": ["ela-district-a"]
}

Responses

Response example

{
    "meta": {
        "status": true,
        "timestamp": 1389193100,
        "records": 1
    },
    "data": {
        "reference": "ela-district-a",
        "description": "Content pool for ELA District A",
        "name": "ELA 2015 District A",
        "status": "published",
        "dt_created": 2015-01-08T07:34:00Z,
        "dt_updated": 2015-01-08T07:34:00Z
    }
}

Set Pools

Create new Item pools for the specified Item bank.

You would want to use this to create a new Item pool based on specific Items, Activities, or Items and Activities that have specific Tags.

See Using Item Pools to Create Content Snapshots for more information.

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.

Endpoint /{LTS_VERSION}/itembank/pools
HTTP method POST
Action type "set"

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.

  • pools array[object]

    A list of Item pools to create.

    Maximum entries: 50

    • reference string

      The unique Item pool reference.

    • name string

      A human readable name used to identify the Item pool.

    • content object

      Configuration for Items and/or Activities to add to the Item pool. The content must contain at least one valid entry.

      • item_references array[string]

        Item references to add to the pool.

      • activity_references array[string]

        Activity references to add to the pool.

      • tags array[TagsV2] array[object]

        Includes Items and Activities which have been assigned to specific Tags or Tag combinations to be added into the Item pool.

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

        There are two modes of operation for specifying Tags.

        Simple

        A list of TagsV2 objects. For each Tag:

        • the type attribute is mandatory, and
        • the name attribute is optional.

        Advanced

        Each entry can consist of an array of filtering options for required_tags and additional_tags.

        • required_tags array[TagsV2]

          A list of TagsV2 objects, in which the content must be tagged with all Tags in the array.

        • additional_tags array[TagsV2]

          (optional) A list of TagsV2 objects, in which the content must be tagged with at least one Tag in the array.

      • item_tags array[TagsV2]

        The same as pools[].content.tags, but only matching Items will be added using this Tag list.

      • activity_tags array[TagsV2]

        The same as pools[].content.tags, but only matching Activities will be added using this Tag list.

        Note All Items associated with the matching Activities will be added regardless.

    • status string

      The publishing status of the Item pool.

      Default: published

      Possible values

      • published
      • unpublished

    • overwrite boolean

      (optional) Overwrite the Item pool if the Item pool reference already exists.

      Default: false

    • ignore_empty_additional_tags boolean

      (optional) Controls whether content matching the additional_tags must return at least one result when using the advanced Tag combinations.

      By default, if there are no matches from the specified additional_tags, the required_tags matches will be ignored and no results will be returned. Set this option to true to override this functionality and always include results that match the required_tags.

      Default: false

    • set_unpublished_to_published boolean

      (optional) Set all content to published when added to the Item pool.

      By default, unpublished content cannot be added to Item pools. You can use this to include content regardless of its publishing status.

      Default: false

    • description string

      (optional) A description of the Item pool. This description only appears when retrieving Item pools using the GET /itembank/pools endpoint.

Request body example

{
    "pools": [
        {
            "reference": "new_test_pool",
            "name": "New test pool",
            "description": "This is a test pool",
            "content": {
                "item_references": [
                    "dataapi_test_001"
                ],
                "activity_references": [
                    "CCASWinter14G06AVE"
                ],
                "tags": [
                    {
                        "type": "course",
                        "name" : "commoncore"
                    }
                ]
            }
        }
    ]
}

/*
* Advanced Tag combination example.
*
* The below Tag combinations example will add:
*   1) any content tagged with all tagnames of tagtype "course"
*   2) any content tagged with:
*        (foo: bar AND baz: *) AND (qux: quux OR corge: * OR grault: garply)
*/
{
    "pools": [
        {
            "reference": "new_test_pool",
            "name": "New test pool",
            "description": "This is a test pool",
            "content": {
                "tags": [
                    {
                        "type": "course"
                        // Tag name is optional
                    },
                    {
                        "required_tags": [
                            {
                                "type": "foo",
                                "name": "bar"
                            },
                            {
                                "type": "baz"
                                // Tag name is also optional in advanced Tag usage
                            }
                        ],
                        "additional_tags": [
                            {
                                "type": "qux",
                                "name": "quux"
                            },
                            {
                                "type": "corge"
                            },
                            {
                                "type": "grault",
                                "name": "garply"
                            }
                        ]
                    }
                ]
            }
        }
    ]
}

Responses

A JSON object containing a job_reference that can be used against the jobs endpoint to track the completion of the (asynchronous) request.

Response example

{
    "meta": {
        "status": true,
        "timestamp": 1389178000,
        "records": 1
    },
    "data": [
        {
            "pool_reference": "new_test_pool",
            "job_reference": "987y12nflkdv"
        }
    ]
}

Update Pools

Update existing Item pools to add or overwrite content.

You would want to use this to make amendments or corrections to existing Item pools.

Note Items pools are designed to be a snapshot of an Item bank. For large changes, it is highly recommended to create a new Item pool instead of modifying an existing Item pool. This reduces the risk of making unintended changes to live assessments.

See Using Item Pools to Create Content Snapshots for more information.

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.

Endpoint /{LTS_VERSION}/itembank/pools
HTTP method POST
Action type "update"

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.

  • pools array[object]

    A list of Item pools to update.

    Maximum entries: 50

    • reference string

      The unique Item pool reference.

    • name string

      A human readable name used to identify the Item pool.

    • content object

      Configuration for Items and/or Activities to add to the Item pool. The content must contain at least one valid entry.

      • item_references array[string]

        Item references to add to the pool.

      • activity_references array[string]

        Activity references to add to the pool.

      • tags array[TagsV2] array[object]

        Includes Items and Activities which have been assigned to specific Tags or Tag combinations to be added into the Item pool.

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

        There are two modes of operation for specifying Tags.

        Simple

        A list of TagsV2 objects. For each Tag:

        • the type attribute is mandatory, and
        • the name attribute is optional.

        Advanced

        Each entry can consist of an array of filtering options for required_tags and additional_tags.

        • required_tags array[TagsV2]

          (mandatory) A list of TagsV2 objects, in which the content must be tagged with all Tags in the array.

        • additional_tags array[TagsV2]

          (optional) A list of TagsV2 objects, in which the content must be tagged with at least one Tag in the array.

      • item_tags array[TagsV2]

        The same as pools[].content.tags, but only matching Items will be added using this Tag list.

      • activity_tags array[TagsV2]

        The same as pools[].content.tags, but only matching Activities will be added using this Tag list.

        Note All Items associated with the matching Activities will be added regardless.

    • status string

      The publishing status of the Item pool.

      Default: published

      Possible values

      • published
      • unpublished

    • overwrite boolean

      Controls whether to only update Items and Activities that already exist in the Item pool.

      When set to true, only the existing Item pool objects listed in pools[].content will be overwritten with the latest content in the Item bank.

      Default: false

    • set_unpublished_to_published boolean

      (optional) Set all content to published when added to the Item pool.

      By default, unpublished content cannot be added to Item pools. You can use this to include content regardless of its publishing status.

      Default: false

Request body example

{
    "pools": [
        {
            "reference": "new_test_pool",
            "name": "Updated test pool",
            "description": "This is a test pool",
            "content": {
                "item_references": [
                    "dataapi_test_001"
                ],
                "activity_references": [
                    "CCASWinter14G06AVE"
                ],
                "tags": [
                    {
                        "type": "course",
                        "name" : "commoncore"
                    }
                ]
            }
        }
    ]
}

Responses

A JSON object containing a job_reference that can be used against the jobs endpoint to track the completion of the (asynchronous) request.

Response example

{
    "meta": {
        "status": true,
        "timestamp": 1440467404
    },
    "data": [
        {
            "pool_reference": "new_test_pool",
            "job_reference": "8f49db43-0d54-4fc5-8154-a721b0334898"
        }
    ]
}
Was this article helpful?

Related articles


Did you arrive here by accident? If so, learn more about Learnosity.