Best practices for using the Microsoft Learn Platform API's Catalog Endpoints

This article describes the best practices for using the Learn Platform API's Catalog Endpoints.

Understand the Terms of Service

Although the Learn Platform API's Catalog Endpoints are publicly available and free to use, users are subject to the Microsoft API Terms of Use. Read and understand the API Terms of Use before using the Learn Platform API and before including the output in any production environment.

Understand the limitations of the Learn Platform API's Catalog Endpoints

See Limitations in the Learn Platform API's Catalog Endpoints Feature overview article.

Understand the Learn content model

In order to use the Learn Platform API's Catalog Endpoints response effectively, it’s important to understand the types of content available in Microsoft Learn and their relationships to one another. Review the Learn content model article for more information.

Notably:

UID stands for Unique ID and is unique for each content object. If a UID changes, even if the title or other metadata stays the same, the content is considered as a new object.
Modules are the core object within the Learn training catalog. They're all capable of standing alone, in the sense that they teach a scenario or concept end-to-end within them and don't require taking prerequisite modules. For some, this is it and they aren't a part of a learning path. For others, they're bundled together in one or more learning paths that take a user through building more advanced concepts. A module doesn't have to be a part of a learning path, or it can be a part of one or more.
Units aren't written as standalone content. They're intended to be taken in a specific order for the module. For this reason, the scenario of getlist of all units isn't a supported use case.

Understand how localization works in Learn and how localized content is reflected in the API output

Microsoft Learn supports over 65 locales on the site and much of the content is translated into these locales. We aim to make the content available in all the languages that the products being taught in the content available in, but not all locale experiences have localized content available.

When a locale record doesn't have the associated translation available, the content on the site and the API response “falls back” to English as the default. In the API output, you see English metadata in other locale responses when fall back happens.

When updates are published to the English content, our localization pipelines work to get the localized versions updated as soon as possible – usually within a few days of the original change. You can see a full list of supported locales in the Microsoft Learn site footer (select on the language you're viewing). Each of these locales can be queried with the Learn Platform API's Catalog Endpoints using the locale filter.

Our training content completion records are locale-agnostic, meaning, we don't differentiate localized versions of content as separate objects in our user training completion records. No matter what language a user completes a training in, they receive credit for the overall object, and we don't store a reference to what language it was completed in. This locale-agnostic completion means if you implement the Learn Platform API's Catalog Endpoints in your learning experience, you need to take it into account and, if you load the content objects in as separate objects, implement an equivalency between them so that no matter which language the user completes the training in, they get credit for it in the other languages and not have to retake it.

Understand how content versioning works in Learn and how it's reflected in the API output

Notably, content is being updated all the time. We publish available updates twice a day. They may either be minor, such as minor text changes, or major, such as major revisions, additions, or deletions. In general, the content portfolio is managed as a massive, highly governed open-source project with thousands of contributors, and as such, changes are happening all the time. If you use the Learn Platform API's Catalog Endpoints in your production system, you should be aware of this and have your system able to handle it.

When new content objects are added, they appear as a new object (identified by UID) in the response. When content is modified, you can tell based on its last_modified value. When content is deleted, the content object is removed from the response. Although there's sometimes a slight delay on content being updated in the API response, when a user follows the URL to the content, they'll always see the most current information. In the case of deletions, the old URL will redirect to the new content or experience, or to the next best option.

There are no references to content versions at this time beyond the updatedAt date.

Refresh the data regularly

If you're using the catalog information from the Learn Platform API's Catalog Endpoints to support your business processes, or displaying for customers as a part of your site experience, make sure that you refresh the content at least once a day.

Review the recommendations the developer documentation

The Learn Platform API's Catalog Endpoints developer documentation has a full list of the data provided as a part of the response, and recommendations on how each field is recommended to be used to support great learning experiences.

Understand the query logic

There are many filters available to use to prefilter the response, so that you only get what you’re looking for and can handle smaller file sizes. You can see the full list of query filters in the Learn Platform API's Catalog Endpoints Developer reference article. Notably, you need to form the query correctly and if you’re using more than one query parameter in the request, the query is assessed using the AND operator.

Next steps

For more information to support you with the Learn Platform API's Catalog Endpoints, review the following articles:

Last updated on 2026-02-11