Skip to content

Plays API#

Read one play from a game data feed: its game and play ids, when it happened, and its clean video where one has arrived. Stories and Clips can show plays. Each response carries the same version the content changes feed reports for the play.

Endpoint Summary#

Endpoint Description
GET /api/plays/by-id/{id} One play by its id, with its version

Get a Play (GET /api/plays/by-id/{id})#

GET /api/plays/by-id/{id}
x-storyteller-api-key: your-api-key-here

id is the play's id, as a play item in the content changes feed gives it. The play must be in your tenant, which the API key decides.

Successful responses carry Cache-Control: private, no-store.

Example Response#

{
  "id": "55555555-5555-4555-8555-555555555555",
  "version": "00000000002C9A61",
  "game": { "provider": "stats-feed", "id": "game-1001" },
  "play": { "provider": "stats-feed", "id": "12" },
  "actionType": "Dunk",
  "period": 2,
  "gameClock": "7:34",
  "eventTimeUtc": "2026-10-20T23:45:12Z",
  "cleanCopy": {
    "url": "https://videos.example.com/clean.mp4",
    "thumbnailUrl": "https://videos.example.com/clean.jpg",
    "revision": "4f0c2e",
    "durationMs": 6400
  },
  "clipId": "66666666-6666-4666-8666-666666666666"
}

Response Fields#

Field Type Description
id string The play's id
version string or null The version the content changes feed reports for this state of the play. Opaque: compare it for equality. Null if the play has not been recorded in the feed. It moves when anything below changes.
game, play object The game's and the play's ids in the game data feed: provider (string or null, when the feed named none) and id
actionType string or null The kind of play, as the feed names it
period integer or null The period the play happened in
gameClock string or null Minutes and seconds left in the period, such as 7:34
eventTimeUtc string or null When the play happened, UTC
cleanCopy object or null The play's clean video, where one has arrived: url, thumbnailUrl, revision (opaque; it changes when a new cut arrives) and durationMs
clipId string or null The Clip made from the play, if any

A play's descriptive facts are what the game data feed supplied: the league's own data is authoritative. New fields may be added; ignore any you do not recognise.

Error Handling#

All errors are RFC 7807 Problem Details.

404 Not Found when the play does not exist, has been deleted, or is not in your tenant:

{
  "status": 404,
  "type": "https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.4",
  "title": "Not Found",
  "detail": "Play with id 55555555-5555-4555-8555-555555555555 not found",
  "instance": ""
}

A play item that the feed lists as deleted reads as 404.

401 Unauthorized without a valid Server App key (see Authentication).