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.

Some terms are used multiple times, such as ‘content’ or ‘id’, in which case the usage is contextual to the containing object.

JSON object	Object composition	Contains	Typical use case
“article” (Object)		A set of data, objects and values that compose all the content making up an article.	An article or page in your website or app.
	“id” (String)	The article ID.	To identify a specific article.
	“clientId” (String)	The unique identifier for the client.	Used to filter a client’s data.
	"version" (Integer)	By default, set to the latest version of the article.	All other versions of the article are held in configuration management and available to be called.
	“slug” (String)	Free-text descriptor for the article.	Can be used to filter and sort. Written without spaces so it can be used in creating a unique URL.
	"publishDate" (String)	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.
	“pinned” (Boolean)	Toggle true or false to give the article pinned status.	To prioritise selected content over other, non-pinned, content. If requested by specifying pinned content in the sort query parameter, it appears before other content in search results.
	“heroMedia” (Object)	Delivers the headline information for your articles and pages; specifically an image or video along with its title and a summary text.	See HeroMedia object entry, below.
	“author” (Object)	The name, job title, image URL, and social media fields for the author of the article. This field is omitted if empty.	See dedicated Author object entry, below.
	“singlePage” (Boolean)	Asserts that this is a page (true), or an article (false).	If `false` the general use case is that this is an article shown with a timestamp in a rolling feed of content sorted by publish time. `true` is for everything else, more likely a static page, such as Contact us, or global components like the website footer.
	"linkedIds” (List of objects)	A delimited list of data providers and their internal data IDs to source a list of content from a third party specific to a player, match, venue, competition, or other entity. The format is: `{` text: "Wembley Stadium", sourceSystem: "OPTA_FOOTBALL_VENUE", sourceSystemId: "5" `}` This field is omitted if empty.	To pull data from third party sources. See linkedIds dedicated row entry below.
	“language” (String)	Sets the language field. This field follows Best Current Practice (BCP) 47 - Language Tags - a standardised code used to identify languages on the internet.	API calls can return the languages associated with an article that is set up to link to multiple versions in other languages, or it can return the other versions of an article linked by language. For more detail, see the dedicated document: Localisation for articles and pages
	“readTimeMinutes” (Integer)	An approximate read time for the article. This field is omitted if empty.	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”.
	"categories” (List of Objects)	A list of article categories, pre-set in Cortex and selected from a drop-down list.	To position the article and in the creation of unique URLs. See the “categories” object entry below. For more detail, see the dedicated document: Content categories for articles and pages
	"displayCategory” (Object)	An object comprising a category ID and the category name. This is a single instance of a category object that is identified as the displayCategory in order to ensure an article has a primary or default category for those occasions when there are multiple categories.	To identify the given category as the primary category. This is then used to, for example, create the URL and display given articles in a primary location. See the [displayCategory dedicated object listing below.
	“tags” (List)	A 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.
	“sponsors” (List of objects)	A list of sponsors, each comprising fields for a sponsor image url, sponsor text, and a sponsor link url. This field is omitted if empty.	See dedicated sponsors object explanation, below.
	"source” (Object)	Identifies a data source system in a readable text string, and in the form of a unique ID, along with a Boolean to enable an overwrite in Cortex. This field is omitted if empty.	This field is for internal use only. See dedicated "source" object link, below.
	"articleMetadata” (Object)	Two strings providing text representing the meta-title and meta-description of the article, used in the context of how search engines display content on search results pages. This field is omitted if empty.	Typically the article “title” and “summary” would be used as the metatitle and description, but these articleMetadata fields would be considered overrides See dedicated object link, below.
	“content” (Object)	A list of content objects that together comprise the article. This field is omitted if empty.	See the “content” object entry below.
	“blocked” (Boolean)	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.	Restrict access on the basis of authorisation or entitlement. If the user must be logged in and no token is provided, or the user lacks a required role, or the user lacks a required entitlement then blocked will be set to true.
	“auth” (object)	Fields declaring restrictions, including that a user must be logged in, verified and over 18, or that a user must have certain entitlements before accessing this article or page. Also specifies whether the article should be blocked or hidden from users who do not meet these requirements.	See auth object entry below.
	"lastModified" (Object)	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.
	"hasGeoBlocking" (Boolean)	Users can be either blocked from (true) or allowed (false) access to the article on the basis of their location. The server-side logic sets this flag 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.
	“videoMetadata” (Object)	Object providing metadata and statistical information for the video.	Full description in object definition below
	“sponsor” (Object)	Instance of a ‘sponsors’ object, comprising an image, some text and a link to a sponsor’s web page.	See the dedicated Sponsors object entry.

“auth” (object)	(Component of an “article” object.)	Fields declaring restrictions, including that a user must be logged in, verified and over 18, or that a user must have certain entitlements before accessing this article or page. Also specifies whether the article should be blocked or hidden from users who do not meet these requirements. This field is omitted if empty.	To provide permissions-based access to articles on the basis of the user status, as described for the restrictions and entitlements entries below.
	“loginRequired” (Boolean)	Article access requires the user to be logged in (true) or it does not require the user to be logged in (false).	To give or withhold access to the article.
	“roles” (Array of strings)	List of roles assigned to the article which the user must have in order to access the article. When the checkboxes are toggled it will add/remove `ROLE_VERIFIED_` / `ROLE_OVER18_` from the array.	Verified means the user must have verified their email address within Cortex’s SSO (single sign on) product. Used, for example, to ensure data integrity in the user database and accurate statistics in user responses. Over 18 means the user must have confirmed they are over 18 as part of their registration or login using Cortex’s SSO.
	“entitlements” (List)	List of entitlements from which the user must have at least one in order to access the article, such as a membership level.	Types of content can be exclusive to a category of member defined by the entitlement. For example, only a Gold member might have access to a club’s streaming service. This can also be used to drive purchases of memberships, season tickets, or other registrations. It could also be used to restrict access to users with a certain category of membership, such as juniors.
	"restrictionType" (String)	This field is one of: `restrictionType: "HIDDEN"` `restrictionType: "BLOCKED"` It is selected from a drop-down menu in Cortex. If this field is left empty, it is 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.	The field set in Cortex is either empty, ‘hidden from user' (the fan never sees the article at all), or the ‘user is blocked’ from seeing this article (the fan can see the article in the list but cannot access the full article - for example, in the manner of a paywall).

“heroMedia” (Object)	(Component of an “article” object.)	A set of data, objects and values (listed below) that deliver the headline information for your articles and pages; such as its title and a banner image.	Headline information for the article, such as its title and summary.
	“title” (String)	The title of the article.
	“summary” (String)	The article summary text.
	“content” (Object)	The main body content. While there are dozens of fields that compose the content object, note that within the heroMedia context this is only allowed to be either an image or a video (even though it uses the full content structure).	See the dedicated Content object entry, below.

“author” (Object)	(Component of an “article” object.)	The name, job title, an image URL, and social media fields for the author of the article.
	“name” (String)	Author’s name. This field is omitted if empty.
	“title” (String)	Author’s title. This field is omitted if empty.
	“imageUrl” (String)	Web address for the author image. This field is omitted if empty.
	“socialHandles” (Array)	An array in which each entry has three fields of type string, one for each of a social media provider, handle and link. Note that the handle field is optional. This object is omitted if empty.	To link readers to the author’s social media.

“linkedIds” Object	(Component of an “article” object)	An object comprising a list of text strings, each one comprising a textual identifier, the Source System and its ID. Fields listed below. These fields are omitted if empty. Example: `{` text: "Wembley Stadium", sourceSystem: "OPTA_FOOTBALL_VENUE", sourceSystemId: "5" `}`	To source data from third party providers.
	“text” (String)	Text string identifying the data item.
	“sourceSystem” (String)	A text string identifying the data source.
	“sourceSystemId” (String)	A unique identifier for the data item in the source system; for example, “5” in the above example represents Wembley Stadium.
“categories” (Object)	(Component of an “article” object)	An array of objects, each comprising an ID for an article category and a text string giving the category a self-explanatory name, such as: “News” or “MatchReports”	To group articles according to set topics.
	“id” (String)	Article’s assigned category ID.
	“text” (String)	Intuitively sensible category name.
“displayCategory” (Object)	(Component of an “article” object).	An object that is a single instance of a category object.	This is a single category that is identified as the displayCategory in order to provide a primary category to assign if there is a choice.
	“id” (String)	The article category's unique ID.
	“text” (String)	Text string giving the category a self-explanatory name, such as: “News” or “Match Reports”.
“sponsors” (Object)		Note that all fields are optional. Therefore it is important to plan for: - Link only (typically, show the URL as the sponsor) - Text only (typically, show the text as the sponsor) - Image only (show the image as the sponsor) - Link and text (show the text but as a link) - Link and image (show the image but as a link) - Link, text and image (show the image, as a link, with text as alt text)	Giving a presence on the page or in the app for a sponsor, comprising an image, some text and a link to their page.
	“text” (String)	Text context for the sponsor.
	“imageUrl” (String)	Text of the full URL to pull in the image.
	“linkUrl” (String)	Text of the full URL link to the sponsor’s chosen web page.
“articleMetadata” (Object)	Component of “article” object.	Two strings providing text representing the meta-title and meta-description of the article, used in the context of how search engines display content on search results pages. This object and its fields are omitted if empty.	Typically the article “title” and “summary” would be used as the metatitle and description, but these articleMetadata fields would be considered as overrides.
	“title” (String)	Text string of the article meta-title.
	“description” (String)	Text description of the article content, articulated to work well in search results.

“Content” (Object)	(Component of an “article” and a “heroMedia” object.)	The main body content for a page or article comprised of fields listed below. Note that while “heroMedia” includes an entire content object block, it will only ever use an image or a video.	Populating web and app page locations with content.
	“id” (String)	Alphanumeric unique identifier for the content.
	“contentType” (String)	Textual statement of the content type from the list of content objects listed below; namely: TEXT, VIDEO, IMAGE, GALLERY, PROMO, QUOTE, CLOUD_MATRIX, RELATED_CONTENT, POLL, ADVERT, COLLECTION, CUSTOM, FEED, BUTTON, FORM, LIVE_BLOG.	Flags the appropriate display framing for the content. Each is described in detail below.
“TEXT” (Object)	Component of a “Content” object.	Identifiers and format information for a text element within a content block.	To enter a text element within a content block.
	“id” (String)	Unique identifier for the content.
	“contentType” (String)	Type identifier (TEXT)
	“content” (String)	The content for the block, in HTML or Markdown format.
	“isHtml” (Boolean)	Flag to assert if the content is pure HTML (if set to true) or a combination of html and markdown (if set to false).
“VIDEO” (Object)	Component of a “Content” object.	Source and identification data to find, fetch and play a video on a website or app.	To place video content into the article.
	“id” (String)	Unique identifier for the video.
	“contentType” (String)	Textual assertion that this is a VIDEO. `contentType=VIDEO`
	“title” (String)	Title of the video. Only displayed in Gallery Views. This field is optional.	Primary caption or title for the video.
	“content” (String)	Optional descriptive text to go below the video.	Secondary caption or description for the video.
	“videoThumbnail” (String)	The thumbnail to be used for the video. This field is optional.
	“link” (String)	Share link for the video. This field is sometimes used to source and generate the video instead of the sourceSystem field (below).	To provide a shareable link for the video.
	“sourceSystem” (String)	Identifies the third party system from which the video is sourced, and therefore which player to use.
	“sourceSystemId” (String)	The unique ID of the video on the source system.
“IMAGE” (Object)	Component of a “Content” object.	Source and identification data to find, fetch and display an image on a website or app.	To place images into the article.
	“id” (String)	Unique identifier for the image.
	“contentType” (String)	Textual assertion that this is an image. `contentType=IMAGE`
	“content” (String)	Optional description of the image.
	“title” (String)	Optional title of the image.
	“image” (String)	The URL for the image fetch.
	“imageThumbnail” (String)	The URL for the image thumbnail to be used for the image. This field is optional. Note that if the front-end website or app supports the thumbnail field and no thumbnail is provided by the Cortex user, the client should ensure the front-end defaults to using the main image as the thumbnail.	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 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.
	“link” (String)	The URL to which the user is taken if they click on the image. This field is optional.
	“altText” (String)	Alternative text used to describe the appearance or function of an image. If present, should be inserted in the `alt` image tag attribute.
	“openInNewTab” (Boolean)	If set to true, the URL entered into the link field (above) will open in a new tab.
“GALLERY” (Object)	Component of a “Content” object.	Source and identification data to fetch, populate and display a gallery of images on a website or app.	To display a gallery element populated with images.
	“contentType” (String)	Textual assertion that this is a gallery. `contentType=GALLERY`
	“title” (String)	Title for the whole gallery.
	“id” (String)	Unique identifier for the Gallery element.
	“appearance” (String)	Asserts how the gallery should appear. There are currently two options: `Type: "CAROUSEL"` or `Type: "GRID"`
	“children” (Array)	Array of content blocks comprising a list of IMAGE objects to render in the gallery.
“PROMO” (Object)	Component of a “Content” object.	The content and framing elements for a promo asset.	A promo asset delivers dynamic content, with variants based on the end user's personal characteristics such as their age, location or membership status.
	“id” (String)	Unique identifier for the promo asset.
	“contentType” (String)	Textual assertion that this is a PROMO object. `contentType=PROMO`
	“sourceSystemId” (String)	The unique ID of the promo asset block from the promo blocks management system.	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: https://developer.cortextech.io/docs/how-to-display-promo-assets-using-headless-integration . Use the ID to construct an embed code for the promo asset as described in this guide: https://developer.cortextech.io/docs/how-to-display-promo-assets-using-an-embed-code
“QUOTE” (Object)	Component of a “Content” object.	The framing elements and text for a quotation in an article.	To enter a quotation into an article.
	“id” (String)	Unique identifier for the Quote element.
	“contentType” (String)	Textual assertion that this is a QUOTE object. `contentType=QUOTE`
	“text” (String)	The quote itself.
	“title” (String)	Role or descriptor for the quote author.
	“author” (String)	Name of the quote’s author.
“CLOUD_MATRIX” (Object)	Component of a “Content” object.	The framing elements and text for a Cloud Matrix video feed.	Used to render video content from a Cloud Matrix feed (Cloud Matrix is a video service provided by StreamAMG).
	“id” (String)	Unique identifier for the CLOUD_MATRIX element.
	“contentType” (String)	Textual assertion that this is a CLOUD_MATRIX object. `contentType=CLOUD_MATRIX`
	“title” (String)	Title of the cloud matrix feed.
	“feedUrl” (String)	The URL to the cloud matrix feed.
“RELATED_CONTENT” (Object)	Component of a “Content” object.	Framing and fields to create a list of associated articles within this article.	Typically used to create a block in the middle or bottom of the article with a list of associated articles for the fan to jump to. Note that including related content requires a subsequent call to the content API to fetch the articles captured by this setup.
	“id” (String)	Unique identifier for the Related Content element.
	“contentType” (String)	Textual assertion that this is a RELATED_CONTENT object. `contentType=RELATED_CONTENT`
	“title” (String)	Title of the related content.
	“tags” (Array of Strings)	Defined tags used to find, filter and sort related content.	Tags can be combined (using AND and OR) with categoryIds and linkedIds to further filter and sort the list.
	“categoryIds” (Array of Strings)	Defined category IDs to search by to find related content.	Similarly to tags, categoryIds can be used to create a list of articles for a fan to jump to. They can be combined (using AND and OR functions) with tags and linkedIds to further filter and sort the list.
	“linkedIds” (Array of linkedIds)	List of linked IDs to search on to find related content.	Similarly to tags and categoryIds, linkedIds can be used to create a list of articles for a fan to jump to. They can be combined (using AND and OR functions) with tags and categoryIds to further filter and sort the list.
	“articleIds” (Array of Strings)	Specific article IDs for related articles.
“POLL” (Object)	Component of a “Content” object.	Provide the elements required to create a poll in an article.	Render a poll into an article.
	“id” (String)	Unique identifier for the poll.
	“contentType” (String)	Textual assertion that this is a POLL. `contentType=POLL`
	“pollId” (String)	The poll ID.	Note that the pollId and the SourceSystemId are the same value. The pollId is no longer used, but remains present for legacy usages. sourceSystemId is the correct field to use.
	“SourceSystemId” (String)	A unique identifier for the poll.	Use this unique identifier to construct an embed code for the poll and include it into your article using this guide: https://developer.cortextech.io/docs/how-to-embed-a-poll
“ADVERT” (Object)	Component of a “Content” object.	The fields and framing elements required to create an embed code for an advertisement, pulled from a third party advertisement provider. To construct an embed code, three items are requires: the platform, the ID for the account within that platform, and the ID for the ad within that account. These are found in the fields: sourceSystem, sourceSystemId and content.	To render an advert, pulled in from a third party advertisement management system.
	“id” (String)	Unique identifier for the advert.
	“contentType” (String)	Textual assertion that this is an ADVERT. `contentType=ADVERT`
	“content” (String)	The user-defined identifier for the advert; for example, “BannerAd123”.
	“sourceSystem” (String)	The platform of the advert, for example: `sourceSystem=GOOGLE_AD_MANAGER`
	“sourceSystemId” (String)	Unique identifier of an account within the advertisement provider’s source system (for example, a specific account within Google Ad Manager)	sourceSystemId is the ID of the relevant account within the advertisement provider’s internal system.
	“platforms” (Array)	An array of strings, declaring the supported platforms. Options are: "WEB", "IOS", and "ANDROID".	Platforms should be configured in order that they do not attempt to load this content if the relevant device type is omitted.
“COLLECTION” (Object)	Component of a “Content” object.	The values and framing elements to gather blocks together into a collection.	For lengthy content, blocks can be added to a collection to hide them from the main or initial view. Typically this might be used for FAQs or terms and conditions.
	“id” (String)	Unique identifier for the collection element.
	“contentType” (String)	Textual assertion that this is a COLLECTION. `contentType=COLLECTION`
	“title” (String)	The name of the collection.
	“children” (Array)	List of content blocks comprising the collection.
	“appearance.type” (String)	Controls the appearance of the collection - can be set to `ACCORDION` or `TAB`
“CUSTOM” (Object)	Component of a “Content” object.	Values and framing for creating custom content.	Custom blocks are used when the front end requirement is outside of the capabilities of the templated content blocks. For more detail, see the document: Custom content blocks
	“id” (String)	Unique identifier for the custom element.
	“contentType” (String)	Textual assertion that this is a CUSTOM content block. `contentType=CUSTOM`
	“customContentType” (String)	The type of the custom content block. The equivalent of the contentType field in a standard content block.	Used to indicate how each custom content block should be rendered.
	customContent (Object)	Custom content block object as defined in the Custom Content Block creation process within Cortex.
“FEED” (Object)	Component of a “Content” object.	Values and elements required to create a feed.	Used to provide a list, carousel, or other collection of Cortex articles, created in Cortex. NOTE: Feeds appear to be similar to Related Content, however, feeds have more powerful filtering capabilities, and a single feed can be saved centrally in Feed Builder and re-used in feed blocks multiple times. For more detail, see the document: Feed builder.
	“id” (String)	Unique identifier for the feed block.	The ID is used to construct an API call to fetch the feed that has been built in Feed Builder.
	“contentType” (String)	Textual assertion that this is a FEED. `contentType=FEED`
	“title” (String)	Title of the feed. This field is optional.
	“sourceSystemId” (String)	The unique ID of the feed in the context of the source system.
“BUTTON” (Object)	Component of a “Content” object.	Values and framing elements required to add a button to your content.	Add a call to action button to your article or page.
	“id” (String)	Unique identifier for the button element.
	“contentType” (String)	Textual assertion that this is a BUTTON. `contentType=BUTTON`
	“title” (String)	The label on the button.
	“link” (String)	The destination to which a user is taken if they click the button.
	“openInNewTab” (Boolean)	If set to TRUE, the link is opened in a new tab. If set to FALSE, opens in the current tab.
“FORM” (Object)	Component of a “Content” object.	Values and framing elements to embed a form into your web or app content.	Render a data capture form on the website or app. This is achieved by constructing an embed code using the form’s ID. For more detail, see the document: How to embed a form.
	“id” (String)	Unique identifier for the form element.
	“contentType” (String)	Textual assertion that this is a FORM. `contentType=FORM`
	“formId” (String)	The form’s ID.	Note that the formId and the SourceSystemId are the same value. The formId is no longer used, but remains present for legacy usages. sourceSystemId is the correct field to use.
	“sourceSystemId” (String)	A unique identifier for the form.
“LIVE_BLOG” (Object)	Component of a “Content” object.	The values and framing required to deliver a live blog.	To render a live blog into website or app content by using the sourceSystemId to construct an embed code for the live blog, as detailed in the document: How to embed a live blog.
	“id” (String)	Unique identifier for the LIVE_BLOG element.
	“contentType” (String)	Textual assertion that this is a LIVE_BLOG. `contentType=LIVE_BLOG`
	“sourceSystemId” (String)	Unique identifier for the LIVE_BLOG in the context of the source system.

“videoMetadata” (Object)	Component of a ‘content’ object.	Values and framing elements for video content.	To facilitate the presence of video in web or app content.
	“isFree” (Bool)	If ‘true’, the video is free to watch and use without any restrictions.	Establish presence or otherwise of e.g., licensing, permissions and usage limitations.
	“plays” (String)	Records the number of plays the video has received.	Analytics.
	“views” (String)	Records the number of views the video has received, as distinct from plays.	Analytics.
	“msDuration” (String)	The duration of the video in milliseconds.
	“accountId” (String)	A unique identifier for the account that uploaded the video.	To track the video back to its source, manage the video's permissions, verify the ownership of a video, and to gather data for analytics, such as the countries from which it has been viewed.
	“playerId” (String)	A unique identifier for the video player that is being used to play the video. It is used to track the video back to the player and to manage the video's playback.	Analytics: to track the performance of a video player, such as the number of videos played, the average playback time, and the most popular players. Troubleshooting: Player ID can be used to troubleshoot problems with video playback, such as buffering, crashes and codec issues. Ad targeting: Player ID can be used to target ads to specific users or groups of users.