Introduction

It is the responsibility of your website or app to make API calls to pull an article or page into your site. This document provides a specification of the API call constructs that will achieve this; beginning with the most common and then following on with all the call options.

Articles - API call constructs

Within the content screens of Cortex, there are two types of content: Article and Page. The differences are primarily in the way the two are used in terms of presentation. An article generally has a date stamp and is part of a time-sorted series. A page is generally static content, such as a ‘contact us’ page. For API call purposes, they can be considered to be equivalent.

Common API calls

Before we look at the many API call options available, here are examples of the most commonly used API call constructs.

API call for a single article using the article ID

💻

GET {environment-id}/v2/articles/{articleId}?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

{articleId} is the article’s unique ID, which can be found in the Cortex platform.

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

For example, this call returns a single article with the article ID a37403aa-0cb7-4c75-8465-eb43a2c3083e from the client with ID DEMO.

💻

GET https://article-cms.cortextech.io/v2/articles/ca0e730e-b99a-4eb5-bf95-9ecca4077b4a?clientId=DEMO

API call for a single article using the article slug

The slug is a string set manually or automatically in Cortex, that provides a short context for the article. It is unique within the client ID, and therefore can be used as a unique identifier for the article or page. It can be used in an API call to retrieve an article, like this:

💻

GET {environment-id}/v2/articles/slug/{slugText}?clientId={clientId}

In which:

{environment-id} and {clientId} are as described above.

{slugText} is the string entered into or generated by the slug field for the article or page in Cortex.

For example, this call will return the list of articles from the client with ID “DEMO” with the slug text that matches the string “they-think-its-all-over”.

💻

GET https://article-cms.cortextech.io/v2/articles/slug/they-think-its-all-over?clientId=DEMO

Note the slug text is written without spaces in order that it can be used in the automatic generation of a unique URL.

API call using a query

A query can be made for articles and pages with specified search text, like this:

💻

GET {environment-id}/v2/articles/search?clientId={clientId}&query={searchText}

{environment-id} and {clientId} are as described above.

{searchText} is the text to search for in selecting articles and pages to fetch.

For example, this call will return all of the articles that match to the client with ID “DEMO”, containing the search text: “betting”:

💻

GET https://article-cms.cortextech.io/v2/articles/search?clientId=DEMO\&query=betting

The query= parameter delivers a complex search of the article for the string parameter using ElasticSearch.

Further call options

There are many fields you can choose to include in the API call. The following example includes all of them, each is then explained, below.

💻

GET {environment-id}/v2/articles?clientId={clientId}&pinned={pinned}&page={page}&size={size}&sort={sortField}&tags={tags}&notTags={notTags}&title={title}&singlePage={singlePage}&language={language}&?fallbackLanguages={fallbackLanguages}categoryId={categoryIds}&slug={slug}&categorySlug={categorySlug}&linkedIds={linkedIds}&articleId={articleIds}

In which:

{environment-id} and {clientId} are as described above.

{pinned} is a Boolean. If set to true, the endpoint returns articles and pages that have been pinned in Cortex. If set to false, it returns articles and pages that have not been pinned. If omitted, both pinned and non-pinned content will be provided.

{singlePage} is a Boolean. If set to false it will return content that are not pages; that is, it will return articles, the general use case for which is anything shown with a timestamp in a rolling feed of content sorted by date and time of publication. Alternatively, if set to true this will return pages. These might include static content (such as the ‘Contact Us’ page), global components (such as the website footer) or configuration files (such as a list of redirects). The default value is false.

{page} is the index of the page to return. The default is page=0, meaning only one page - the first page - should be returned.

{size} is the page size. To limit and manage the size of the data, it is recommended never to exceed a value greater than 1000 items. The default is 100. For example, by default the API call includes singlePage=false&page=0&size=100. This means the call is requesting articles, it is requesting one page of articles - the first page - and that each page comprises 100 content items.

{sortField} is a string representing the sort options. Technically it is possible to sort on any field, however in practical terms, the most commonly used are publishDate and pinned. Putting a '-' in front of the parameter will sort in descending order. The default sort option is to sort, firstly, by whether the article is pinned or not, and then by publication date (in descending order); so: -pinned,-publishDate

{tags} is a comma-delimited list of tags. It returns only the articles with those tags. Tags can be added to an article or page in the Cortex CMS.

{language} is a code for the declared language for the article, set from a drop-down list in Cortex, and following the BCP-47 standard.

{fallbackLanguages} is the list of fallback languages, to be used if there is no version of a given article available in the primary language. Fallback languages should be comma separated, and specified in the order in which they should be prioritised.

{notTags} is similar to tags, but lists the tags to exclude.

{title} is a string. It returns all articles in which the string features as all or part of the title.

{categoryIds} is a comma-delimited list of category IDs. It returns only those articles with those category IDs.

{slug} is a string. It returns only the article or page with this string as the slug. It requires an exact match.

{categorySlug} is a string. It returns only those articles or pages with this string as the category slug.

{articleIds} is a comma-delimited list of article IDs, which can be found in Cortex.

{linkedIds} is a delimited list of data providers and their internal data IDs. The semicolon is the delimiter. The format is SOURCE:ID,ID,ID;SOURCE:ID. For example OPTA_FOOTBALL_PLAYER:3992,3492;OPTA_FOOTBALL_TEAM:t43

LinkedIds also carries an optional query parameter: linkedIdsOperator which can have a value of AND or OR - defaulting to OR if not supplied. This query parameter controls whether all the listed linkedIds must match or at least one. So, for example, you could pull all the articles for a football player AND their team; that is, returning only articles that match both parameters - or pull all the articles for a football player OR their team; that is, any article that matches the player or the team, not necessarily both.