Introduction

Categories and tags are the main fields used to identify and filter articles and pages. While tags are free-form text and are created within each instance of content, categories are set up centrally for all of a client’s content. Once set, categories are then selected from a drop-down list within each article or page when it is created.

Categories are therefore unique within the client context and can be reliably used, for example, as a flag for placement or display criteria (such as changing the background colours), or in the creation of a unique URL. Tags are less reliable in this way, because they are free-text and therefore prone to user error.

The body of this document addresses the criteria for API calls using content categories.

Fields and parameters within categories

Most commonly, categories are used to organise and group content. A category called HOMEPAGE, for example, can be used to classify content as appropriate for the home page. If content within the API call is then sorted by publication date, the home page is dynamically updated in real time each time new content within the HOMEPAGE category is published.

Content can also be assigned multiple categories, meaning it can be grouped in multiple ways. For example, the same content might appear on several different web pages.

Categories can be used to find related content. A search returning all content assigned a given category can achieve this.

Primary category

Although articles can be assigned multiple categories, they can only be assigned one Primary Category. There are often occasions when a single category needs to represent the article, or there is only space for one category in a given situation, and in these circumstances the primary category is used.

The main use case for the primary category is in the creation of a unique URL. Since an article can only reside on one URL and has only one primary category, the category slug from the primary category is generally used to construct the URL.

The second common usage occurs when categories are displayed to fans. For example in menus or in navigation such as the website ‘breadcrumbs’ or article labelling. In these cases, the primary category is used.

Category title

The text used to name the category is used to identify it in Cortex and in the drop-down menu presented to the content creator. It may also be visible to fans, such as in links to pages that are dedicated to that category, in menu items or links, or in the ‘breadcrumbs’ that aid navigation on the fan's display. It is therefore important to give the category an intuitively usable name.

Category ID

All categories are automatically assigned a unique category ID upon creation.

Sub-categories

Categories can be assigned sub-categories. For example, the category NEWS could have sub-categories called TEAM, CLUB and FOUNDATION. While a call on the category NEWS will return every article in the NEWS category and all its sub-categories, a call on the sub-category CLUB will only return news articles assigned to the CLUB sub-category.

Category tags

Not to be confused with tags in an article, categories can also be assigned a free-text tag or tags.

The category tag allows another layer of flexibility in working with categories. The categories endpoint can be called and results filtered on the basis of the category tags. For example, you could request all of the categories with the category tag: app only, or all the categories with the category tag web only, in order to filter content designed for use only with the app or for use only with the web.

The category tag can also be used to handle categories in exceptional ways. For example, to highlight a category in the list if the category tag is, for example, tag=featured.

Slug

Each category is given a category slug. The slug is generally used to provide a short contextual string for the category. If not populated with bespoke text by the creator in Cortex, it will be automatically generated using the category title as its basis, along with the slug of the parent category, if applicable. The category slug must be in lower-case, and alpanumeric plus some special characters if suitable for URLs. Spaces, and special characters that are not supported in URLs, are not permitted, because the slug is often used in the generation of unique URLs.

Language

There is an option when creating a category to assign a language from a drop-down list. At the same time, the category name and slug can be given translations for ease of use in the alternative language. These fields can be useful in creating web pages in multiple languages whilst retaining the site structure and fixed set of categories. So, for example, a Spanish version of the web site could use the translated version of the slug text in its URL in order to ensure the user is taken to the Spanish site and article.

It is important to be aware that selecting a language and populating the name and slug with translated versions does not change the category ID (nor does it affect the actual language of the text in the article). Every individual article is written in one language and has one category ID for each assigned category. So, for example, there may be two articles addressing the same topic, one in Spanish and one in English. They are both in the NEWS category, and have the same category ID, however it is up to the fan-facing design to use the language settings to ensure the consumers are displayed the appropriate content.

API calls using categories

Below are the most common API calls you are most likely to need in working with categories.

To return a list of all the created categories:

💻

GET {environment-id}/v2/categories?clientId={clientId}

In which:

{environment-id} is the URL for stage (test) or production (live).

• Stage: https://stage-article-cms.cortextech.io
• Production: https://article-cms.cortextech.io
• Production (US environment): https://article-cms.cortextech.us

{clientId} is your client ID, assigned during onboarding.

So, for example, this call fetches a list of all the category objects associated with the client ID DEMO:

💻

GET https://article-cms.cortextech.io/v2/categories?clientId=DEMO

To return a particular category’s definition:

💻

GET {environment-id}/v2/categories/{categoryId}

In which:

{environment-id} is the base URL, depending on environment, as detailed above.

{categoryId} is the category ID for which you want to see the detail. This can be obtained from the endpoint to return all categories, described above, or from the Cortex platform.

So, for example, this call will pull in the details of the category with ID 16a1828e-754e-4824-8ed3-48aa7885203e.

💻

GET https://article-cms.cortextech.io/v2/categories/16a1828e-754e-4824-8ed3-48aa7885203e

In that example, the JSON looks like this:

{"status":"success",
 "data":
 {"id":"16a1828e-754e-4824-8ed3-48aa7885203e",
  "clientId":"DEMO",
  "slug":"news-match-reports",
  "text":"Match reports",
  "lastModified":{"date":"2023-08-22T13:58:38.798Z"}
 }
}

To return article(s) from the category, by ID:

💻

GET {environment-id}/v2/articles?clientId={clientId}&categoryId={categoryId}

In which:

{environment-id} is the base URL, depending on environment, as detailed above.

{clientId} is your client ID, assigned during onboarding.

{categoryId} is a comma-delimited list of category IDs for which you want to return associated articles. This can be obtained from the endpoint to return all categories, described above, or from the Cortex platform.

So, for example, this call will fetch all articles associated with the category IDs ab3c9e35-c101-4ea2-8d8c-5e86d069fd0c or 03b681f4-c137-4cf6-a24d-a4a2250f5dc1:

💻

GET https://article-cms.cortextech.io/v2/articles?clientId=DEMO&categoryId=ab3c9e35-c101-4ea2-8d8c-5e86d069fd0c,03b681f4-c137-4cf6-a24d-a4a2250f5dc1

Additional parameters can be added. For details, please refer to the document: API call specifications for articles and pages

To return article(s) from the category, by slug:

💻

GET {environment-id}/v2/articles?clientId={clientId}&categorySlug={categorySlug}

In which:

{environment-id} is the base URL, depending on environment, as detailed above.

{clientId} is your client ID, assigned during onboarding.

{categorySlug} is the category slug for which you want to return associated articles. This can be obtained from the endpoint to return all categories, described above, or from the Cortex platform.

So, for example, this call will call in all articles associated with the category slug news.

💻

GET https://article-cms.cortextech.io/v2/articles?clientId=DEMO&categorySlug=news

Additional parameters can be added. For details, please refer to the document: API call specifications for articles and pages

Tree structures

If there are sub-categories set up in Cortex, adding the modifier tree=true will return the category listings with the category and sub-category parent/child relationships implicit to the response.