Catalog API response: Stories

Field reference and example JSON for paginated Stories responses from the Catalog API.

Stories list responses use the pagination envelope and fields below. For the shared content model, geo-targeting, and extraInfo, see Response principles.

Stories-specific fields: isLive, pages[], titleImageUrl, htmlUrl. Stories do not have top-level subtitle, duration, videoRenditions, translatedDescriptions, or translatedSubtitles. pages[].videoRenditions appears when direct video access is enabled for your feed.

classDiagram
direction TB

class Story {
  string id
  string type
  string title
  string description
  number version
  string[] aspectRatios
  string status
  boolean isLive
  string createTime
  string updateTime
  Thumbnail[] thumbnails
  string titleImageUrl
  GeoTargeting geoTargeting
  StoryMetadata metadata
  string executionTimeType
  string htmlUrl
  Page[] pages
  object[] labels
  StoryExtraInfo extraInfo
  string defaultLanguage
  object translatedTitles
  string competitionId
  string publishMethod
  CreationSettings creationSettings
  StoryGame game
  number rating
}

class Thumbnail {
  string url
  string aspectRatio
}

class GeoTargeting {
  string[] includedGeos
  string[] excludedGeos
}

class ProviderRef {
  string provider
  string providerId
  number wscId
}

class StoryMetadata {
  ProviderRef competition
  ProviderRef[] competitions
  ProviderRef game
  ProviderRef team
  ProviderRef player
  ProviderRef round
  ProviderRef season
}

class Page {
  string id
  number index
  number duration
  Thumbnail[] thumbnails
  string createTime
  string updateTime
  PageMetadata metadata
  PageExtraInfo extraInfo
  VideoRendition[] videoRenditions
}

class VideoRendition {
  string url
  string fileType
  string aspectRatio
  number bitRate
  Resolution resolution
}

class Resolution {
  string level
  number height
  number width
}

class PageMetadata {
  ProviderRef competition
  ProviderRef[] competitions
  ProviderRef game
  ProviderRef team
  ProviderRef player
  ProviderRef round
  ProviderRef season
}

class PageExtraInfo {
  string homeTeam
  string awayTeam
  string propertyId
  string propertyName
  string gameId
  string teamId
  string playerId
  string roundId
  string seasonId
}

class StoryExtraInfo {
  string homeTeam
  string awayTeam
  string propertyId
  string propertyName
  string rating
  string isCurrentlyLive
  string activeLabels
  string gameId
  string teamId
  string playerId
  string roundId
  string seasonId
}

class CreationSettings {
  string creationTimePeriod
  string ruleName
  string storyType
}

class StoryGame {
  string gameDate
  string gameStatus
  string stadium
  GameParticipant[] participants
}

class GameParticipant {
  string name
  ProviderRef ids
  string type
  number score
}

Story --> Thumbnail : thumbnails 0..*
Story --> GeoTargeting : geoTargeting 1
Story --> StoryMetadata : metadata 1
Story --> Page : pages 0..*
Story --> StoryExtraInfo : extraInfo 1
Story --> CreationSettings : creationSettings 1
Story --> StoryGame : game 0..1
StoryGame --> GameParticipant : participants 0..*
GameParticipant --> ProviderRef : ids

StoryMetadata --> ProviderRef : entities
Page --> Thumbnail : thumbnails 0..*
Page --> PageMetadata : metadata 1
Page --> PageExtraInfo : extraInfo 1
Page --> VideoRendition : videoRenditions 0..*
VideoRendition --> Resolution : resolution
PageMetadata --> ProviderRef : entities

Response shape

List responses wrap stories in a pagination envelope. Each element of result is a Story object.

Pagination envelope

Property (dot notation)	Type	Example
`totalItems`	number	`1`
`result[]`	array	`[ {...} ]`

Story object properties

The following table lists properties on each story in result[], using dot notation for nested fields.

Property (dot notation)	Type	Example
`id`	string	`697a1360b1559e82007800e4`
`type`	string	`Story`
`title`	string	`Example story title`
`description`	string	`Example story description`
`version`	number	`7`
`aspectRatios[]`	string[]	`["Vertical"]`
`status`	string	`Active`
`isLive`	boolean	`false`
`createTime`	string (ISO-8601)	`2026-01-28T13:47:12.03Z`
`updateTime`	string (ISO-8601)	`2026-01-29T10:14:09.518Z`
`thumbnails[]`	object[]	`[ {...} ]`
`thumbnails[].url`	string	`https://cdn.example.invalid/thumbnails/story_square.jpg`
`thumbnails[].aspectRatio`	string	`Square`
`titleImageUrl`	string or null	`null`
`geoTargeting`	object	`{...}`
`geoTargeting.includedGeos`	string[] or null	`null`
`geoTargeting.excludedGeos`	string[] or null	`null`
`metadata`	object	`{...}`
`metadata.competition`	object or null	`{ "provider", "providerId", "wscId" }`
`metadata.competitions[]`	object[]	same shape as `metadata.competition`
`metadata.game`	object or null	`{ "provider", "providerId", "wscId" }`
`metadata.team`	object or null	`{ "provider", "providerId", "wscId" }`
`metadata.player`	object or null	`{ "provider", "providerId", "wscId" }`
`metadata.round`	object or null	`{ "provider", "providerId", "wscId" }`
`metadata.season`	object or null	`{ "provider", "providerId", "wscId" }`
`executionTimeType`	string	`None`
`htmlUrl`	string	`https://example.invalid/stories/story_9f3c2a1b.html`
`pages[]`	object[]	`[ {...} ]`
`pages[].id`	string	`697a135cb1559e82007800e3`
`pages[].index`	number	`0`
`pages[].duration`	number	`12.3123`
`pages[].createTime`	string	`2026-01-28T13:47:08.341Z`
`pages[].updateTime`	string	`2026-01-28T13:47:08.341Z`
`pages[].thumbnails[]`	object[]	`[ {...} ]`
`pages[].thumbnails[].url`	string	`https://cdn.example.invalid/thumbnails/page_vertical.jpg`
`pages[].thumbnails[].aspectRatio`	string	`Vertical`
`pages[].metadata`	object	`{...}`
`pages[].metadata.competition`	object or null	`null`
`pages[].metadata.competitions`	object[] or null	`null`
`pages[].metadata.game`	object or null	`{ "provider", "providerId", "wscId" }`
`pages[].metadata.team`	object or null	`{ "provider", "providerId", "wscId" }`
`pages[].metadata.player`	object or null	`{ "provider", "providerId", "wscId" }`
`pages[].metadata.round`	object or null	`{ "provider", "providerId", "wscId" }`
`pages[].metadata.season`	object or null	`{ "provider", "providerId", "wscId" }`
`pages[].extraInfo`	object	`{...}`
`pages[].extraInfo.homeTeam`	string	`Charlotte Hornets`
`pages[].extraInfo.awayTeam`	string	`Sacramento Kings`
`pages[].extraInfo.propertyId`	string	`c81e728d9d4c2f636f067f89cc14862c`
`pages[].extraInfo.propertyName`	string	`NBA`
`pages[].extraInfo.gameId`	string	`1522500076`
`pages[].extraInfo.teamId`	string	`1610612758`
`pages[].extraInfo.playerId`	string	`1642928`
`pages[].extraInfo.roundId`	string	`6`
`pages[].extraInfo.seasonId`	string	`2025`
`pages[].videoRenditions`	object[]	same shape as Moments and Videos `videoRenditions`
`labels[]`	object[]	`{ "title", "identifier" }`
`extraInfo`	object	`{...}`
`extraInfo.homeTeam`	string	`Charlotte Hornets`
`extraInfo.awayTeam`	string	`Sacramento Kings`
`extraInfo.propertyId`	string	`c81e728d9d4c2f636f067f89cc14862c`
`extraInfo.propertyName`	string	`NBA`
`extraInfo.rating`	string	`3`
`extraInfo.isCurrentlyLive`	string	`False`
`extraInfo.activeLabels`	string	`[]`
`extraInfo.gameId`	string	`1522500076`
`extraInfo.teamId`	string	`1610612758`
`extraInfo.playerId`	string	`1642928`
`extraInfo.roundId`	string	`6`
`extraInfo.seasonId`	string	`2025`
`defaultLanguage`	string (Language)	`und`
`translatedTitles`	object	`{}` or `{ "en": "...", "es": "..." }`
`competitionId`	string	`2`
`publishMethod`	string	`MANUAL`
`creationSettings`	object	`{...}`
`creationSettings.creationTimePeriod`	string	`None`
`creationSettings.ruleName`	string or null	`null`
`creationSettings.storyType`	string or null	`null`
`game`	object or null	`{...}`
`game.gameDate`	string	`2025-07-21T02:00:00`
`game.gameStatus`	string	`Ended`
`game.stadium`	string	`Thomas & Mack Center`
`game.participants[]`	array	`[ {...} ]`
`game.participants[].name`	string	`Charlotte Hornets`
`game.participants[].ids`	object	`{ "provider", "providerId", "wscId" }`
`game.participants[].ids.provider`	string or null	`NBAStatsFeeds`
`game.participants[].ids.providerId`	string or null	`1610612766`
`game.participants[].ids.wscId`	number	`1004`
`game.participants[].type`	string	`Team`
`game.participants[].score`	number	`83`
`rating`	number	`3`

Nested metadata.* entities have provider as null. A provider name appears only on game.participants[].ids.provider. Each entity object also has providerId and wscId.

executionTimeType is None when no workflow context is set. Stories are the only content type that carries another value (PreGame, InGame, PostGame).

htmlUrl is unique to your feed. Compare and cache by id, not by URL. See Response principles.

extraInfo is an open dictionary. Keys vary by sport. See Response principles.

Object keys in translatedTitles match the Language enum names (for example, en, es, en_US, or und for default). An empty object {} is valid when no translated titles are present.

Example JSON - doesn't contain all properties

{
  "totalItems": 1,
  "result": [
    {
      "id": "697a1360b1559e82007800e4",
      "type": "Story",
      "title": "Example story title",
      "description": "Example story description",
      "version": 7,
      "aspectRatios": ["Vertical"],
      "status": "Active",
      "isLive": false,
      "createTime": "2026-01-28T13:47:12.03Z",
      "updateTime": "2026-01-29T10:14:09.518Z",
      "thumbnails": [
        {
          "url": "https://cdn.example.invalid/thumbnails/square.jpg",
          "aspectRatio": "Square"
        },
        {
          "url": "https://cdn.example.invalid/thumbnails/twotothree.jpg",
          "aspectRatio": "TwoToThree"
        },
        {
          "url": "https://cdn.example.invalid/thumbnails/horizontal.jpg",
          "aspectRatio": "Horizontal"
        }
      ],
      "titleImageUrl": null,
      "geoTargeting": {
        "includedGeos": null,
        "excludedGeos": null
      },
      "metadata": {
        "competition": {
          "provider": null,
          "providerId": null,
          "wscId": 2
        },
        "competitions": [
          {
            "provider": null,
            "providerId": null,
            "wscId": 2
          }
        ],
        "game": {
          "provider": null,
          "providerId": "1522500076",
          "wscId": 104138149
        },
        "team": {
          "provider": null,
          "providerId": "1610612758",
          "wscId": 1026
        },
        "player": {
          "provider": null,
          "providerId": "1642928",
          "wscId": 9988274
        },
        "round": {
          "provider": null,
          "providerId": "6",
          "wscId": 0
        },
        "season": {
          "provider": null,
          "providerId": "2025",
          "wscId": 0
        }
      },
      "executionTimeType": "None",
      "htmlUrl": "https://example.invalid/stories/697a1360b1559e82007800e4.html",
      "pages": [
        {
          "id": "697a135cb1559e82007800e3",
          "index": 0,
          "duration": 12.3123,
          "thumbnails": [
            {
              "url": "https://cdn.example.invalid/thumbnails/page_vertical.jpg",
              "aspectRatio": "Vertical"
            }
          ],
          "createTime": "2026-01-28T13:47:08.341Z",
          "updateTime": "2026-01-28T13:47:08.341Z",
          "metadata": {
            "competition": null,
            "competitions": null,
            "game": {
              "provider": null,
              "providerId": "1522500076",
              "wscId": 104138149
            },
            "team": {
              "provider": null,
              "providerId": "1610612758",
              "wscId": 1026
            },
            "player": {
              "provider": null,
              "providerId": "1642928",
              "wscId": 9988274
            },
            "round": {
              "provider": null,
              "providerId": "6",
              "wscId": 0
            },
            "season": {
              "provider": null,
              "providerId": "2025",
              "wscId": 0
            }
          },
          "extraInfo": {
            "homeTeam": "Charlotte Hornets",
            "awayTeam": "Sacramento Kings",
            "propertyId": "c81e728d9d4c2f636f067f89cc14862c",
            "propertyName": "NBA",
            "gameId": "1522500076",
            "teamId": "1610612758",
            "playerId": "1642928",
            "roundId": "6",
            "seasonId": "2025"
          }
        }
      ],
      "labels": [],
      "extraInfo": {
        "homeTeam": "Charlotte Hornets",
        "awayTeam": "Sacramento Kings",
        "propertyId": "c81e728d9d4c2f636f067f89cc14862c",
        "propertyName": "NBA",
        "rating": "3",
        "isCurrentlyLive": "False",
        "activeLabels": "[]",
        "gameId": "1522500076",
        "teamId": "1610612758",
        "playerId": "1642928",
        "roundId": "6",
        "seasonId": "2025"
      },
      "defaultLanguage": "und",
      "translatedTitles": {},
      "competitionId": "2",
      "publishMethod": "MANUAL",
      "creationSettings": {
        "creationTimePeriod": "None",
        "ruleName": null,
        "storyType": null
      },
      "game": {
        "gameDate": "2025-07-21T02:00:00",
        "gameStatus": "Ended",
        "stadium": "Thomas & Mack Center",
        "participants": [
          {
            "name": "Charlotte Hornets",
            "ids": {
              "provider": "NBAStatsFeeds",
              "providerId": "1610612766",
              "wscId": 1004
            },
            "type": "Team",
            "score": 83
          },
          {
            "name": "Sacramento Kings",
            "ids": {
              "provider": "NBAStatsFeeds",
              "providerId": "1610612758",
              "wscId": 1026
            },
            "type": "Team",
            "score": 78
          }
        ]
      },
      "rating": 3
    }
  ]
}

Updated about 1 month ago

Did this page help you?