List linking API (get lists related to a module)

This article explains how the list linking API answers the question “Which lists are there for my Module?”

What is the List linking API?

The list linking API allows you to find a list or set of lists that are attached to a given point on the Talis Aspire Reading Lists hierarchy, using a calculable/guessable URI structure. The hierarchy is the tree of courses and programmes at your institution. Read more about how the hierarchy is updated.

What can it be used for?

Using this API, you can develop a widget or extension for your Learning Management System, to direct students on a course or module page direct to the correct lists within Talis Aspire Reading Lists.

How do I use the API?

The get related lists API requires that you are using an authenticated API client.  You can find more about the fundamentals of getting setup in the API Primer.

The get related lists API, for a given hierarchy node (such as a module, unit, department etc) allows you to:

  • find published lists 
  • find draft lists
  • have private lists included in the search results

See the API documentation at:

The get related lists API replaces the legacy unauthenticated route documented below.


How do I use the legacy List Linking API?

Note: This legacy API documented in this section will be deprecated at some point in the future. You are encouraged to switch to the authenticated version of this route so that you can take advantage of being able to find draft and private lists which are excluded from this legacy route.

This API can be used in two forms, simple or advanced. Both forms rely on adding extra path information onto the end of the hierarchy URI.

In both cases, you can get the information back as HTML, RDF/XML or JSON as per the same principles outlined in our Linked data API specification.

You may find that you need to work around some browser security features when using these APIs. You are strongly advised to call these APIs from a server rather than directly in a browser.

When used in HTML mode, the API shows a table of available lists for the user to choose from. If there is only one list linked to a matching hierarchy node, Talis will redirect to that list rather than show the table. This feature allows you to provide guessable links direct to reading lists within your Learning Management System.

Simple (without time periods)

In this mode, simply take the hierarchy URI and append either “/lists”, “/lists.json” or “/lists.rdf” onto the end of it. For example, let’s start with

By default, if you do not specify a time period, you will receive all lists attached to the hierarchy node regardless of time period.

IMPORTANT: Node codes must be lower case in the URI

Advanced (with time periods)

If you have time periods configured, you can instruct the API only to return lists for a given module within a given active time period (i.e. semester or term). For a description of time periods and how they work, please read the time periods article.

To do this, add the time period slug onto the end of the URI, for example:

The slug usually takes the defined time period title, replacing all ‘spaces’ with a ‘-‘ and removing all symbols (note that a ‘-‘ is not treated as a symbol and will be preserved in the slug). For example ‘Semester 1&2, 2011-12’ becomes ‘Semester-1-2-2011-12’.

The slug is configurable though - so if you need it to match a specific string that your learning management system knows, then just raise a support ticket asking us to do this for you.


The API supports JSONP to get around Cross Site Scripting issues. You can specify a callback function, using the cb parameter:

Who can use this API?

Anyone can use this API, although excessive requests will be rate limited, except by prior arrangement.

This API is used in both the Moodle and Blackboard integrations. Read more about our learning management system integrations.


Have more questions? Submit a request


Please sign in to leave a comment.