Introduction

The Media section of the Cortex platform provides a digital asset management (DAM) service. While URLs for images and other media files can easily be added from the Cortex DAM to articles, pages, player profiles and more, it is often the case that website or app content needs to display an image or video outside of those contexts. For this reason, media files can be fetched directly via an API call.

This document firstly exemplifies the API constructs that will fetch the stored media files, and, lastly, provides an example of the content of the resultant JSON response.

The media API call structure

Media data can be fetched using an API call structured as follows.

💻

GET {environment-id}/v1/media?clientId={clientId}&page={page}&size={size}&sort={sort}&name={name}&description={description}&fileType={fileType}&tags={tags}&language={language}&manualTags={manualTags}&&linkedId={linkedId}&linkedIds={linkedIds}&linkedIdsOperator={linkedIdsOperator}&to={to}&from={from}

In which:

{environment-id} is the URL for stage (test) or production (live).

• Stage: https://media-stage.cortextech.io
• Production: https://media.cortextech.io
• Production (US environment): https://media-stage.cortextech.us

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

All the other query parameters are optional and are as follows.

{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 number of items to be included on each page. Defines the size of the result set for paginated requests.

{sort} the sorting criteria for the results. Allows ordering of the output based on one or more fields, with an optional ascending or descending order, denoted by “-” for descending. For example ?sort=-publishDate,id

{name} is a the media name as set in the Cortex platform. In other words, using this would return media files with a matching name.

{description} is the media description as set in the Cortex platform. In other words, using this would return media files with a matching description.

{language} is the language set in the Cortex platform. Uses language codes as per the BCP-47 standard. For example language=en.

{fileType} is the type of file to be retrieved, such as an image file format. For example fileType=image/png.

{tags} is the tags specified in the media’s metadata in Cortex. When multiple tags are included in the request, in a comma-delimited list, the media must possess all specified tags. Note that this parameter will match against tags that are either manually entered in Cortex or tags that are automatically generated within Cortex. For example tags=Crest .

{manualTags} is the tags specified in the media’s metadata in Cortex, but including only those that have been added by a Cortex user (i.e. excluding any tags that have been added automatically).

{linkedId} is deprecated.

{linkedIds} is the linked IDs added to media files to link them to a match, player or other sporting entity. Use the format {SOURCE SYSTEM}:{SOURCE SYSTEM ID}. Multiple source systems can be specified by separating them with pipes, while multiple source system IDs can be indicated by separating them with commas. For example linkedIds=OPTA\_FOOTBALL:t56,t67\|OPTA\_RUGBY\_UNION:800.

{linkedIdsOperator} specifies the operator used for querying by multiple source systems using the linkedIds parameter. Possible values for the operator are AND and OR. The default is OR.

{to} specifies an upper limit or endpoint for date filtering in ISO 8601 format, restricting content up to a specific date. For example ?to=2023-11-08T00:00:00.000Z.

{from} is a lower limit or starting point for date filtering in ISO 8601 format, restricting content from a particular date onwards. For example ?from=2023-11-08T00:00:00.000Z.

API call examples

A complete API call, using the tags field to find all media tagged with the string: 'Matchday' looks like this:

💻

GET https://media.cortextech.io/v1/media?clientId=DEMO&tags=Matchday

A call that will fetch all media attributed with the language field: es (Spanish) looks like this:

💻

GET https://media.cortextech.io/v1/media?clientId=DEMO&language=es

The JSON response

The above calls will return the JSON for the client ID DEMO, and the tag ‘Matchday’ in the first instance and the language es (Spanish) in the second case. In both cases, the JSON response looks as follows. Note some peripheral fields and values have been omitted to aid in clarity of reading:

"data":[
  {
    "id":"4095f7ef-9794-4ed6-9162-ebe775a4c37f",
    "name":"Stadium - Wide View",
    "clientId":"DEMO",
    "parentId":null,
    "url":"https://media-cdn.incrowdsports.com/4095f7ef-9794-4ed6-9162-ebe775a4c37f.png",
    "fileName":"4095f7ef-9794-4ed6-9162-ebe775a4c37f.png",
    "fileExtension":"png",
    "fileType":"image/png",
    "description":"Image of the stadium",
    "language":"en",
    "height":714,
    "width":1270,
    "durationSeconds":null,
    "bitrate":null,
    "framerate":null,
    "thumbnailUrl":null,
    "fileSize":2027482,
    "version":{
      "versionNumber":1,
      "versionId":"wL3tCJQyiJWElMjZvFLRusIcA1dqQtKq",
      "versionFileSize":2027482
    },
    "tags":[
      "stadium-wide",
      "Matchday"
    ],
    "generatedTags":[
      "Field",
      "People",
      "Person",
      "MAD 1902",
      "MAD",
      "1902",
      "LA"
    ],
    "source":{
      "sourceSystem":"CORTEX"
    },
    "linkedIds":null,
    "publishDate":"2023-11-08T00:00:00.000Z",
    "mimeType":"image/png"
  }
]