JSON response table for articles and pages

This article tabulates the complete list of JSON objects and data fields you can expect from an article API call, with examples showing how the data is typically used in creating your content.

Overview

Once an API call for content has been made, it returns a JSON response of fields and values for use in the creation of your web or app content display. For an example, see https://article-cms.cortextech.io/v2/articles/ca0e730e-b99a-4eb5-bf95-9ecca4077b4a?clientId=DEMO. This page tabulates the JSON data in the response.


Object compositionContainsTypical use case
articleA set of data, objects and values that compose all the content making up an article. See the table article, below.An article or page in your website or app.

article

Object compositionContainsTypical use case
idString. The article ID.To identify a specific article.
clientIdString. The unique identifier for the client.Used to filter a client’s data.
versionInteger. By default, the latest version of the article will be provided.Troubleshooting.
slugString. Mandatory, and free text in Cortex but with validation to ensure there are no spaces, upper case letters, or special characters. Additionally, a uniqueness constraint is applied, so that no two articles or pages will have the same slug.Typically this would be used to form the last part of the URL on which the article or page will be displayed.
publishDateString. Date of publication, in the time format: 2006-01-02T15:04:05.000Z. This is the ISO 8601 international standard for date and time representation.To indicate the date and time when the content was made available to the public.
pinnedBoolean. true indicates that the article or page has been pinned by the Cortex user.If specified in the sort query parameter, pinned content appears before other content in search results. You might also choose to visually distinguish pinned articles in some way.
heroMediaAn object comprising the headline information for your articles and pages; specifically an image or video along with the title and summary of the article or page. See the table heroMedia, below.Headline information for your articles and pages.
authorAn object comprising the name, job title, image URL, and social media fields for the author of the article. This field is omitted if empty. See the table author, below.Display the author of the article, with links to their social accounts.
singlePageBoolean. true indicates that the content has been set as a page by the Cortex user.If false the content is typically shown as a news a article, i.e. content shown with a timestamp in a rolling feed of content sorted by publish time.

true is typically for everything else, more likely a static page, such as Contact us. It has also been used for global components, like the website footer, or for technical config.
linkedIdsAn array of objects, each of which represents a sporting entity (e.g. a team, venue, player or fixture) and the identifier for that sporting entity as per the system of a data provider such as Opta. This field is omitted if empty. See the table linkedIds, below.Typically, this is used in API calls, e.g. to produce a feed of articles related to a given fixture, team or player. Within the article, it might be used to pull in related articles, or data from other systems, such as to bring in a promo asset for a ticketing promotion for a fixture with a corresponding linked ID.
languageString. Indicates the language of the content. The format follows Best Current Practice (BCP) 47 - Language Tags - a standardised code used to identify languages on the internet.Typically, this is used in API calls e.g. to return articles with a given language associated. Within the article, you might choose to display the language to fans.

For more detail, see the dedicated document: Localisation for articles and pages
readTimeMinutesInteger. Generated automatically or set by the Cortex user.To display a read time to fans to indicate content length and help them to decide which articles they have the time to look at e.g., “3 minute read”.
categoriesList of objects, representing the categories associated to the content, selected from a drop-down list in Cortex. See the table categories, below.To position the content, style it, or to configure content in any other way.

For more detail, see the dedicated document: Content categories for articles and pages
displayCategoryAn object comprising a single category ID and category name.Display as the primary category of the content, i.e. somehow distinguished from the wider list of categories associated to the content. It's also commonly used in the creation of unique URLs, since each category has a unique slug.
tagsA list of strings representing the tags declared in the article or page creation.

Note that tags are free text whereas categories are pre-set for all articles or pages in the wider settings, then selected from a drop-down list within the article; so it is generally best to use categories as this reduces the risk of human error. However, you might use tags where it needs to include a variable.
Identifies and contextualises the content for style, filtering, positioning and so on.
sponsorsA list of objects, representing sponsors, each of which may comprise fields for a sponsor image url, sponsor text, and a sponsor link url.

This field is omitted if empty.
Display an overall sponsor of the content. Note that multiple can be provided. Typically a platform will display up to a certain number of sponsors, and ignore any additional sponsors provided beyond that number. And in some cases, that number is 1.
sourceString, which identifies the source system of the content e.g. where content has been syndicated from a third party CMS.Troubleshooting.
articleMetadataAn object comprising two strings for title and description. Free text, optional, and omitted if empty.Metadata is used by search engines to display content on search results pages, and is therefore relevant to SEO. Typically the metadata would be generated using other fields (e.g. heroMedia.title for meta-title, and heroMedia.summary for the meta-description), with the articleMetadata fields used as overrides.
contentA list of objects that correspond to the content blocks (e.g. image block) added in the Cortex platform. This is omitted if empty. See the table content, below.The main body of the article of page.
blockedBoolean, indicating whether or not the fan is blocked from accessing the main body of the content. For example, because access is restricted on the basis of authorisation and no token has been provided, or access requires an entitlement which the user does not have. When set to false, this flag asserts permission for the user to view the entire article. When set to true, the content array will be stripped from the response and only the article’s hero media will be returned.Provide a visual indication to the fan that they cannot access the content.
authFields declaring restrictions on accessing the content, including that a user must be logged in, verified, over 18, or that a user must have certain entitlements before accessing this content (if a valid and suitable token is not provided in the request, the response will omit the content object). See the table auth, below.Where blocked: true, the details within auth may be used to indicate to the fan how they might access the content, e.g. log in or make a purchase corresponding to the required entitlement.
lastModifiedObject with a string indicating the date of last edit, in the time format: 2006-01-02T15:04:05.000Z. This is the ISO 8601 international standard for date and time representation.Troubleshooting.
hasGeoBlockingBoolean indicating whether geoblocking is enabled. This is set to true if geoBlocking is toggled ON in Cortex and either:
- geoBlocking is set to whitelist mode; or
- geoBlocking’s country list is not empty.
Geoblocking is asserted on the server side. This flag simply indicates whether an article has geoblocking toggled on or off.

Note that geoBlocking and the list of countries to be blocked or permitted are set in Cortex and are not listed in the JSON response. This flag only indicates if geoblocking is in use.

heroMedia

Object compositionContainsTypical use case
titleA string, taken from the title field in the Cortex platform.Primary identifier for the article or page. For example, this may be used as the H1 or title of the web page or app screen showing the article or page, as the main or only text shown to identify the article in a list, or as the meta-title where articleMetadata is not provided.
summaryA string taken from the summary field in the Cortex platform. Optional, omitted if empty.Secondary identifier for the article or page. For example, this may be used as the introduction text on the web page or app screen showing the article or page, as a snippet of the article when shown in a list, or as the meta-description where articleMetadata is not provided.
contentAn object comprising the details of the image or video block added as hero media in the Cortex platform. Fields vary depending on block type, and are identical to the content object in the main body of the article, although, in the context of heroMedia, the block type may be IMAGE or VIDEO only. See the table content, below.Provide hero media - an image or video - for the article or page.

author

Object compositionContainsTypical use case
nameA string, entered as the author's name in the Cortex platform. This is the only mandatory field within author.Where the content's author is displayed to fans, this field would normally be used to display the author's name.
titleA string, entered as the author's title in the Cortex platform. Omitted if empty.Display the author's title.
imageUrlA string, providing a URL added as the author image in the Cortex platform. Omitted if empty.Display an image or graphic representing the author.
socialHandlesAn array of objects, each of which may contain a provider, link and handle. Omitted if empty. See the table socialHandles, below.Display links to the author's social accounts.

socialHandles

Object compositionContainsTypical use case
providerA string, with values selected from a dropdown within the Cortex platform. Accordingly, values may be one of FACEBOOK, REDDIT, TWITTER, TWITCH, YOUTUBE, INSTAGRAM, THREADS, TIKTOK, or OTHER. Mandatory field within socialHandles.To select a social platform-specific graphic or widget, or other platform-specific behaviour. It might also be used as the visible link text, if no handle is provided.
linkA string, providing a URL. Mandatory field within socialHandles.To add a link to the author's social account.
handleA string. Free text and optional within Cortex. Omitted if empty.To display the author's handle, as per the relevant social platform.

linkedIds

Object compositionContainsTypical use case
textA string, typically provided by the linked ID data provider to identify the sporting entity in human readable form. For example "Wembley Stadium". It's an optional field in Cortex, and omitted if empty.Troubleshooting.
sourceSystemA string representing the source system in which the ID has been attributed to the sporting entity. For example "OPTA_FOOTBALL_VENUE". Mandatory.Filtering to find a relevant linked ID, and then it would often be used in API calls as per the linkedIds use cases explained above.
sourceSystemIdA string representing the ID of a sporting entity within the source system. For example, in the case of Wembley Stadium and OPTA-FOOTBALL-VENUE, 5. Mandatory.Used in API calls as per the linkedIds use cases explained above.


categories

Object compositionContainsTypical use case
idA string representing the ID for the category, within the Cortex system.For API calls from the article or page, such as in order to show articles and pages in the same category.
parentIdA string representing the ID for the category's parent category, if applicable.To display categories in a hierarchical structure, such as in a breadcrumb menu.
clientIdA string representing the ID for the client within the Cortex platform.Troubleshooting.
slugString. Mandatory, and free text in Cortex but with validation to ensure there are no spaces, upper case letters, or special characters. Additionally, a uniqueness constraint is applied, so that no two categories will have the same slug.Along with the slug for the article or page, the category slug can be used to construct the URL for the content. Additionally, it may be used in API calls to get other content in the same category, instead of id.
textString. Mandatory, and free text in Cortex.The primary, human-readable identifier for the category. Normally, this is the only part of the category that a fan would see on screen.
i18nAn array of objects consisting of lang, text and slug, provided if translations have been added to the category in Cortex.Show category text and URLs in different languages
afterA string representing the ID for the category's immediate predecessor in the vertical sort order set in the Cortex platform.If showing a list of categories, after may be used to show each category in the correct location in that list, as per the Cortex user's preference.


sponsors

Object compositionContainsTypical use case
textString. Free text and optional in Cortex. Omitted if empty.Where no imageURL is provided, display the sponsor name. Where imageURL is provided, the value for text may be used as alt text.

Alternatively, some implementations have used this as a prefix to the sponsor, so that the Cortex user can add "Sponsored by", "In association with", or something else. Note however that this involves extra work for the Cortex user, so if using it in this way a fallback is recommended.
imageUrlA string, providing a URL added as the sponsor image in the Cortex platform. Optional, and omitted if empty.Render an image representing a sponsor of the content.
linkUrlA string, providing a URL. Optional, and omitted if empty.Typically, where imageUrl is provided, clicking the rendered image would open the URL defined by linkUrl. If there is no imageUrl but there is text, clicking the rendered text would open the URL. Where neither text or imageUrl are provided, you might choose to display the URL itself.

auth

Object composition

Contains

Typical use case

loginRequired





Boolean. If true, this indicates that the content cannot be accessed unless the fan is logged in.

To indicate to fans that they must be logged in to view the content.

roles

An array of strings. If the "Must be verified" is ticked in Cortex then this will include "ROLE_VERIFIED_*"; and if "Must be over 18" is ticked in Cortex then "ROLE_OVER18_*" is included. Content cannot be accessed unless the fan meets these requirements.

To indicate to fans that they must have verified their email address and/or confirm they are over 18, in order to view the content.

entitlements

An array of objects, each of which consists of an id and name and represents an entitlement that a fan must have before accessing the content. For example, the fan might gain an entitlement through a season ticket purchase or membership level.

To indicate to fans that they must make a purchase, or otherwise gain an entitlement, before accessing the content.

restrictionType

String, which will be one of "HIDDEN" or "BLOCKED". It corresponds to a selection made in a dropdown menu in Cortex when adding authorisation requirements as described above. If no selection is made then an empty string - "" - is provided. It is therefore recommended that a default choice is made at the client-side as access is still restricted and control over the outcomes of the restriction should be asserted.

HIDDEN indicates that the Cortex user wants their content to be completely invisible to fans who do not meet the authorisation requirements. BLOCKED indicates that the Cortex user wants fans to see a preview of the content, but be blocked from reading in full until they login or upgrade. The latter is commonly used as the default.

content

Object compositionContainsTypical use case
idA string representing a unique identifier for the content block.Troubleshooting.
contentTypeA string representing the block type, e.g. for an image block the contentType would be IMAGE. Possible values include: TEXT, VIDEO, IMAGE, GALLERY, PROMO, QUOTE, CLOUD_MATRIX, RELATED_CONTENT, POLL, ADVERT, COLLECTION, CUSTOM, FEED, BUTTON, FORM, LIVE_BLOG. The fields that may be contained in each block, and the typical use case for each field, varies based on contentType. Therefore please see the tables below for more details.Determine how the fields in the content block should be handled.
sponsorAn object, representing a sponsor of the block, which may comprise fields for a sponsor image url, sponsor text, and a sponsor link url.Display a sponsor of the block.

Additional fields incontent where contentType is TEXT

Object compositionContainsTypical use case
contentA string representing the text entered by the user into the text block. Typically this will be in markdown format, as that's the result of using the text editor in its default state, but it is also possible for the user to edit the code, so there may be HTML and/or javascript included.Display text in the article or page.
isHtmlBoolean.If true, expect HTML and no markdown. If false expect markdown, or a combination of markdown and HTML.

Additional fields in content where contentType is VIDEO

Object compositionContainsTypical use case
titleString. Free text. Omitted if empty.Primary caption or title for the video.
contentString. Free text. Omitted if empty.Secondary caption or description for the video.
videoThumbnailString, with a URL representing an image. Omitted if empty.The thumbnail to be used for the video in its 'ready to play' state. This may be more relevant for some video players than others, as some will have a suitable 'ready to play' state built-in e.g. the first frame of the video.
linkString, with a URL representing the video. Omitted if empty.This field is sometimes used to source and generate the video instead of the sourceSystemId field (below).
sourceSystemA string representing the video platform selected from a dropdown in Cortex.Identifies the third party system from which the video is sourced, and therefore which player to use.
sourceSystemIdString.The unique identifier of the video within the source system.

Additional fields in content where contentType is IMAGE

Object compositionContainsTypical use case
titleString, with the free text entered into the title field in the Cortex platform. Omitted if empty.Add a primary caption to the image.
contentString, with the free text entered into the description field in the Cortex platform. Omitted if empty.Add a secondary caption to the image.
imageString, with the URL of an image.Display the image referenced by the URL.
imageThumbnailString, with the URL of an image. Omitted if empty.There are two typical use cases.

1. Within a gallery block, the thumbnail can be shown in the list or grid. The main image is then loaded when a thumbnail image is clicked.
2. If the thumbnail is included in the hero media, it can be used on the category page (that is, when you view a list of articles). The main image is then used when viewing the article itself.
linkString, with a URL. Omitted if empty.The URL to which the user is taken if they click on the image.
altTextString, free text, omitted if empty.Alternative text used to describe the appearance or function of an image. If present, should be inserted in the alt image tag attribute.
openInNewTabBooleanIf set to true, the URL entered into the link field (above) will open in a new tab.
deepLinkString, with a URI in the format deeplink-{identifier}://{screenname}/{item}, where {identifier} is a global value set per client instance in Cortex, {screenname} is selected from a pre-set list in Cortex, and {item} is optional and may be a content ID, a match ID, or free text. Omitted if empty.The app screen to which the user is taken if they click on the image.

Additional fields in content where contentType is GALLERY

Object compositionContainsTypical use case
titleString, with the free text entered into the title field in the Cortex platform. Omitted if empty.Title for the whole gallery.
appearanceAn object including either type: "CAROUSEL" or type: "GRID"Display the gallery in either a carousel or grid format, depending on preference of the Cortex user.
childrenAn array of objects, each representing an image block added to the gallery. Each image block within a gallery block may have all of the same fields as described in the context of the standalone image block.Display a gallery, or collection of images.

Additional fields in content where contentType is PROMO

Object compositionContainsTypical use case
sourceSystemIdString, representing the unique ID of the promo asset added to the content.There are two typical use cases:

1. Use the ID to make an API call to get a promo asset, and then render it in the manner described in this guide .
2. Use the ID to construct an embed code for the promo asset as described in this guide.

Additional fields in content where contentType is QUOTE

Object compositionContainsTypical use case
textString, free text.The quote to display, typically in a larger font to pull put from the rest of the content.
titleString, free text. Omitted if empty.Display the role or descriptor for the quote author.
authorString, free text. Omitted if empty.Display the name of the quote author.

Additional fields in content where contentType is CLOUD_MATRIX

Object compositionContainsTypical use case
titleString, with the free text entered into the title field in the Cortex platform. Omitted if empty.Display the title of the cloud matrix component.
feedUrlString, with a URL.Load a Cloud Matrix feed using the provided URL (Cloud Matrix is a video service provided by StreamAMG).

Additional fields in content where contentType is RELATED_CONTENT

Object compositionContainsTypical use case
titleString, with the free text entered into the title field in the Cortex platform. Omitted if empty.Display a title of the related content component.
tagsArray of strings, each representing free text tags entered into the related content block in Cortex. Omitted if empty.Call the content API, as described in this document, with the relevant tag(s) included as parameters, and therefore display content with those tags as related content.
categoryIdsArray of strings, each representing IDs for content categories created in the Cortex platform. Omitted if empty.Call the content API, as described in this document, with the relevant categories included as parameters, and therefore display content with those categories as related content.
linkedIdsArray of objects, each representing linked IDs entered into the related content block in Cortex. A linked ID may consist of three fields, as described elsewhere in this document, including text, sourceSystem, and sourceSystemId. Omitted if empty.Call the content API, as described in this document, with the relevant linked IDs included as parameters, and therefore display content with those linked IDs as related content.
articleIdsArray of strings, each representing IDs for content (articles or pages) created in the Cortex platform. Omitted if empty.Call the content API, as described in this document, with the relevant content IDs, and therefore display the corresponding articles or pages as related content as related content.
relatedContentOperatorString, which will be either AND or ORIf AND, display content which meets all of the selected criteria. If OR, display content which meets any of the selected criteria.

Additional fields in content where contentType is POLL

Object compositionContainsTypical use case
sourceSystemIdA string, with an ID representing a poll created in Cortex.Use this unique identifier to construct an embed code for the poll and include it in the content, as explained in this guide.
pollIdThe same value as sourceSystemId.This field is deprecated but is still present for legacy reasons. It should be ignored and sourceSystemId should be used instead.

Additional fields in content where contentType is ADVERT

Object compositionContainsTypical use case
contentA string, with the free text entered into the Code field in the advert block in Cortex. It is expected that the value entered will be the user-defined identifier of an individual advert in an Ad Manager account (these IDs are referred to as a "code" in Ad Manager).Use in conjunction with the value in sourceSystemId to render an ad from Google Ad Manager.
sourceSystemString, representing a selection from a dropdown labelled Provider in the advert block in Cortex. Currently, only one value is possible, GOOGLE_AD_MANAGERDetermine from which platform an ad will be displayed. Currently only Google Ad Manager is supported, but more may be added in future.
sourceSystemIdString, which is expected to be the identifier of the Ad Manager account. In Ad Manager, this is referred to as the Network code.Use in conjunction with the value in content to render an ad from Google Ad Manager.
platformsAn array of strings, which may be ANDROID, WEB and/or IOS.Determine whether or not to attempt to display the ad on your fan-facing platform (and therefore avoid whitespace if the advert is configured to not show on that platform within the Ad Manager account).

Additional fields in content where contentType is COLLECTION

Object compositionContainsTypical use case
titleString, free text, omitted if empty.The primary heading for the overall collection of tabs or accordions.
contentString, free text, omitted if empty.The secondary heading or description of the overall collection of tabs or accordions.
childrenAn array of objects comprising a title field and children including one or many content blocks, which could be any of the blocks described in this section.The title field would normally be used as a heading for the individual tab or accordion. For example in an FAQ, it would be used as the question. The content within children would then be used as the content within that tab or accordion. In the FAQ example, this would represent the answer to the question.
appearanceAn object including one field type, with a string that may be either TAB or ACCORDIONDetermine how the content within the collection block should be displayed, i.e. either as tabs or accordions.

Additional fields in content where contentType is FEED

Object compositionContainsTypical use case
sourceSystemIdA string, with an ID representing a content feed created in Cortex.Call the feed builder API, as explained in this guide , and therefore display the content included in that feed in a list, carousel or other component.

Additional fields in content where contentType is BUTTON

Object compositionContainsTypical use case
titleString, free text.Display as the label on the button.
linkString containing a URLThe destination to which a user is taken if they click the button.
openInNewTabBooleanOn web, determine whether the link should open in a new tab (if TRUE), or not (if FALSE).

content where contentType is FORM

Object compositionContainsTypical use case
sourceSystemIdA string, with an ID representing a form created in Cortex.Use this unique identifier to construct an embed code for the form and include it in the content, as explained in this guide .
formIdThe same value as sourceSystemId.This field is deprecated but is still present for legacy reasons. It should be ignored and sourceSystemId should be used instead.

content where contentType is LIVE_BLOG

Object compositionContainsTypical use case
sourceSystemIdA string, with an ID representing a live blog created in Cortex.Use this unique identifier to construct an embed code for the live blog and include it in the content, as explained in this guide .

Additional fields in content where contentType is CUSTOM

Object composition

Contains

Typical use case

customContentType

A string, with an ID representing the custom content block created in Cortex.

Determine how the content in a custom block should be displayed.

customContent

An object with model as defined in the custom content block creation process within Cortex.

The content to be displayed within the component powered by the custom content block.