Guides

API call specifications for live blogs

This article provides details of the API calls that can be made in relation to live blogs.

Introduction

The APIs referred to in this document enable a third party system or middleware to manage the creation of live blogs and live blog posts. A typical use case is where there is a requirement to display a single blog with manually-created editorial content alongside automated content, such as that provided in an Opta commentary feed. This approach would simplify and expedite the content creation process. For example, as soon as a goal is scored, an automated post appears in the blog immediately, while the content creator gets to work on adding some colour with their editorial content. In such a use case, it is envisioned that editorial content is created by the admin user within the Cortex platform, while middleware creates automated posts in that same live blog, using the APIs explained below.

Note: It is assumed that all implementations will utilise the embeddable web component provided by Cortex, as explained in How to embed a live blog. Accordingly, this document is focussed on live blog and post creation, as explained above, rather than the APIs and websockets which could be used to fetch live blog data for rendering in a custom fan-facing component.

API keys

Each of the APIs described below require an API key provided as an X-API-Key header. API keys can be provided by Cortex on request.

API call specifications

In all cases the base URL is:

Get live blogs

The following endpoint fetches all live blogs of the client associated to the provided API key.


GET /v1/external/live-blogs

Query parameters

tags: A comma-delimited list of tags. If used, the list of live blogs returned will include only those with at least one of those tags.

linkedIds: A delimited list of data providers and their internal data IDs. The format is SOURCE:ID,ID,ID;SOURCE:ID. For example OPTA_FOOTBALL_PLAYER:3992,3492;OPTA_FOOTBALL_TEAM:t43. If used, the list of live blogs returned will include only those with the corresponding linked IDs added via the Cortex platform.

page: Page number. Defaults to 0.

size: Items per page. Defaults to 50.

sort: Sort field (e.g., -publishDate).

Get a live blog

The following endpoint provides the details of a single live blog, as specified by the value used in place of {iveBlogId}

GET /v1/external/live-blogs/{liveBlogId}

Create a live blog

The following endpoint can be used to create a live blog

POST /v1/external/live-blogs

An example body is shown below.

{
  "title": "Example",
  "summary": "Example live blog",
  "language": "en",
  "publishDate": "2027-01-01T00:00:00Z",
  "liveFrom": "2027-01-01T01:00:00Z",
  "liveTo": "2027-01-01T02:00:00Z",
  "tags": [
    "example"
  ],
  "linkedIds": [
    {
      "text": "Example",
      "sourceSystem": "OPTA_FOOTBALL_MATCH",
      "sourceSystemId": "12345"
    }
  ],
  "themeId": null,
  "sponsors": [
    {
      "imageUrl": "https://media-cdn.incrowdsports.com/72b5d1a2-f095-4679-936a-bf51c8cac705.png",
      "linkUrl": "https://www.cortextech.io/",
      "text": "Cortex"
    }
  ],
  "viewerCount": {
    "enabled": true,
    "minimum": 100
  },
  "personalizedContent": null
}

Get live blog posts

The following endpoint returns all posts of the live blog specified by the value used in place of {liveBlogId}.

GET /v1/external/live-blogs/{liveBlogId}/posts

Get a live blog post

The following endpoint returns details of the post specified by the value used in place of {postId}.

GET /v1/external/live-blogs/{liveBlogId}/posts/{postId}

Create live blog posts

The following endpoint can be used to create a live blog post within a live blog specified by the value used in place of {liveBlogId}. This is the key endpoint for the use case described in the introduction, above.

POST /v1/external/live-blogs/{liveBlogId}/posts

An example body is shown below.

{
  "title": "This is my post title",
  "publishDate": "2027-01-01T01:00:00Z",
  "timestamp": "2027-01-01T00:00:00Z",
  "content": [
    {
      "contentType": "TEXT",
      "content": "This is the text I've added to my text block",
      "isHtml": false
    }
  ],
  "keyEvent": false,
  "postTypeId": null
}

Update a live blog post

The following endpoint can be used to update an existing live blog post.

PUT /v1/external/live-blogs/{liveBlogId}/posts/{postId}

Delete a live blog post

The following endpoint can be used to delete a live blog post.

DELETE /v1/external/live-blogs/{liveBlogId}/posts/{postId}

Create a summary key event

The following endpoint can be used to designate a specified live blog post as a summary key event. That is, in the Cortex-provided embeddable web component, a duplicate of the post would be shown at the top of the blog in the summary section.

Note that there are two overlapping 'key event' concepts in play:

  • Any live blog post can be flagged as a key event using "keyEvent": true, in the body of the live blog post as described above under the heading Create live blog posts. If true then, in the Cortex-provided embeddable web component, styling of the post will be powered by the 'key event' theme fields. Typically, key event posts would be shown with a bold background, to bring fans' attention to that post.
  • A live blog post with "keyEvent": true, can additionally be added to the list of the summary key events, using the endpoint detailed below. The effect in the Cortex-provided embeddable web component is that a duplicate of the post would be shown at the top of the blog in the summary section. These can include a separate title, if required.

POST /v1/external/live-blogs/{liveBlogId}/posts/{postId}/key-events

An example body is shown below.

{
  "title": "Example title to be shown in the summary section only"
}

Get summary key events

The following endpoint returns all summary posts of the live blog specified.

GET /v1/external/live-blogs/{liveBlogId}/key-events

Update summary key events

The following endpoint can be used to update a summary key event.

PUT /v1/external/live-blogs/{liveBlogId}/posts/{postId}/key-events/{keyEventId}

Delete summary key events

The following endpoint can be used to delete a live blog post. Note that this would not delete the original post itself, it would only remove it from the list of summary key events.

DELETE /v1/external/live-blogs/{liveBlogId}/posts/{postId}/key-events/{keyEventId}


Updated 12 days ago

Did this page help you?