API call constructs

Within the Content section of Cortex, content creators can produce two types of content: Article and Page. Within the API the data structure is identical; the division exists to reflect two distinct front end use cases. An article generally has a date stamp and is part of a time-sorted series of news content. A page is generally static content, such as a ‘contact us’ page.

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 {base URL}/v2/articles/{articleId}?clientId={clientId}

In which:

{base URL} is the URL shown below, depending on environment used.

• Standard environment: https://article-cms.cortextech.io
• 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, the following 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 {base URL}/v2/articles/slug/{slugText}?clientId={clientId}

In which:

{base URL} 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, the following 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 field includes validation to ensure it is written without spaces or some special characters, so that it can be used in the automatic generation of a unique URL.

API call using a query

ℹ️

Note: A new advanced search endpoint is available, in beta. Please see the separate document Content Advanced Search .

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

GET {base URL}/v2/articles/search?clientId={clientId}&query={searchText}

{base URL} 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. This may include specific fields to check and the operator to use where there are multiple criteria. For example, the following call would return articles with either the category ID 1234 or the category ID 5678.

GET https://article-cms.cortextech.io/v2/articles/search?clientId=DEMO&query=categories.id:1234+OR+5678

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 {base URL}/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:

{base URL} 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 at least one of 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 at least one of 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.

Where multiple criteria are requested, articles will only be returned if they meet all of the specified criteria. For example, the response to the following request will return all articles with the client ID DEMO, the tag 123, and either of the category IDs 546 or 789.

GET https://article-cms.cortextech.io/v2/articles?clientId=DEMO&tags=123&categoryId=456,789