# Endpoint reference Methods, parameters and responses from the served OpenAPI document. Source: [Endpoint reference](/endpoints/) This reference is generated from the exact document served at [/v1/openapi.json](https://api.live.storyos.ai/v1/openapi.json). Document version: `0.2.1`. It is an NBA integration view of the generic API, describing the sample index and feed route. > **Sample and live replay timestamps** > > An empty sample replay reports the fixture’s first event, or an earlier requested `asOf`. Live feeds instead use the feed’s creation time, or that earlier `asOf`. A live read without replay reports the latest publication commit time. See [Replay](/markdown/replay.md). ## `/v1/fixtures` [#v1fixtures] ### GET — List the sample fixtures and the feeds each serves [#get--list-the-sample-fixtures-and-the-feeds-each-serves] The Game Pulse sample games, newest first. The retained Portland version 1 example (0022501147) is served at its feed route but is not listed. | Parameter | Location | Required | Format | Description | | --------------- | -------- | -------- | ------ | ----------- | | `If-None-Match` | header | No | string | | | Status | Meaning | Response headers | | ------ | ----------------------------------------- | ---------------------------------------------------------------------- | | `200` | The fixture index. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | | `304` | The snapshot has not changed. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | | `405` | Only GET, HEAD and OPTIONS are supported. | `Allow` | **Complete OpenAPI operation** ```json { "operationId": "listNbaAiInsightsFixtures", "summary": "List the sample fixtures and the feeds each serves", "description": "The Game Pulse sample games, newest first. The retained Portland version 1 example (0022501147) is served at its feed route but is not listed.", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The fixture index.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/AccessControlAllowOrigin" }, "Access-Control-Expose-Headers": { "$ref": "#/components/headers/AccessControlExposeHeaders" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FixtureIndex" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } ``` ### HEAD — The fixture index headers without a body [#head--the-fixture-index-headers-without-a-body] | Parameter | Location | Required | Format | Description | | --------------- | -------- | -------- | ------ | ----------- | | `If-None-Match` | header | No | string | | | Status | Meaning | Response headers | | ------ | ----------------------------- | ---------------------------------------------------------------------- | | `200` | The GET headers. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | | `304` | The snapshot has not changed. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | **Complete OpenAPI operation** ```json { "operationId": "headNbaAiInsightsFixtures", "summary": "The fixture index headers without a body", "parameters": [ { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The GET headers.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/AccessControlAllowOrigin" }, "Access-Control-Expose-Headers": { "$ref": "#/components/headers/AccessControlExposeHeaders" } } }, "304": { "$ref": "#/components/responses/NotModified" } } } ``` ### OPTIONS — CORS preflight [#options--cors-preflight] | Status | Meaning | Response headers | | ------ | ------------------------ | --------------------------------------------------------------------------------------------- | | `204` | CORS preflight accepted. | `Access-Control-Allow-Origin`; `Access-Control-Allow-Methods`; `Access-Control-Allow-Headers` | **Complete OpenAPI operation** ```json { "operationId": "preflightNbaAiInsightsFixtures", "summary": "CORS preflight", "responses": { "204": { "$ref": "#/components/responses/Preflight" } } } ``` ## `/v1/fixtures/{fixtureId}/feeds/{feedKey}` [#v1fixturesfixtureidfeedsfeedkey] ### GET — Get the complete active NBA AI Insights snapshot for one fixture [#get--get-the-complete-active-nba-ai-insights-snapshot-for-one-fixture] A bundled sample fixture, or the deployment's public live feed for the fixture. No authentication. Samples use Cache-Control: public, max-age=0, must-revalidate; live feeds use no-store. Both support ETag revalidation. | Parameter | Location | Required | Format | Description | | --------------- | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fixtureId` | path | Yes | string | NBA game ID used as the integrating client's stable fixture identifier. | | `feedKey` | path | Yes | string | Client-recognized feed key. The NBA feed is pulse. | | `atAction` | query | No | integer | Replay: keep only items whose content.actionNumber (the NBA play-by-play actionNumber they attach to) is at or before this value. Sample games and public live feeds; the Portland version 1 fixture returns 400. | | `asOf` | query | No | string | Replay: keep only items whose publishedAt is at or before this RFC 3339 date-time, which must carry a time zone (encode + as %2B). Combined with atAction, an item must satisfy both. Sample games and public live feeds; the Portland version 1 fixture returns 400. | | `If-None-Match` | header | No | string | | | Status | Meaning | Response headers | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------- | | `200` | Complete currently consumable NBA AI Insights snapshot, ordered by active-revision publishedAt newest first with id as the tie-break. A live read without replay uses the latest manifest commit time as snapshotAt. With atAction or asOf, select the highest published revision satisfying both bounds for each item, in the same delivery order and with a distinct ETag. Withdrawn items remain excluded, including from earlier replays. Replay snapshotAt is the newest selected publishedAt. An empty sample replay uses the fixture's first event time; an empty live replay uses the feed creation time. Either uses asOf instead when the requested cutoff is earlier. Portland does not support replay. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | | `304` | The snapshot has not changed. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | | `400` | Request could not be fulfilled. | | | `404` | Request could not be fulfilled. | | | `405` | Only GET, HEAD and OPTIONS are supported. | `Allow` | **Complete OpenAPI operation** ```json { "operationId": "getNbaAiInsightsFixtureFeed", "summary": "Get the complete active NBA AI Insights snapshot for one fixture", "description": "A bundled sample fixture, or the deployment's public live feed for the fixture. No authentication. Samples use Cache-Control: public, max-age=0, must-revalidate; live feeds use no-store. Both support ETag revalidation.", "parameters": [ { "$ref": "#/components/parameters/FixtureId" }, { "$ref": "#/components/parameters/FeedKey" }, { "$ref": "#/components/parameters/AtAction" }, { "$ref": "#/components/parameters/AsOf" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "Complete currently consumable NBA AI Insights snapshot, ordered by active-revision publishedAt newest first with id as the tie-break. A live read without replay uses the latest manifest commit time as snapshotAt. With atAction or asOf, select the highest published revision satisfying both bounds for each item, in the same delivery order and with a distinct ETag. Withdrawn items remain excluded, including from earlier replays. Replay snapshotAt is the newest selected publishedAt. An empty sample replay uses the fixture's first event time; an empty live replay uses the feed creation time. Either uses asOf instead when the requested cutoff is earlier. Portland does not support replay.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/AccessControlAllowOrigin" }, "Access-Control-Expose-Headers": { "$ref": "#/components/headers/AccessControlExposeHeaders" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NbaAiInsightsFeed" } } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "$ref": "#/components/responses/Problem" }, "404": { "$ref": "#/components/responses/Problem" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" } } } ``` ### HEAD — The snapshot headers without a body [#head--the-snapshot-headers-without-a-body] | Parameter | Location | Required | Format | Description | | --------------- | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `fixtureId` | path | Yes | string | NBA game ID used as the integrating client's stable fixture identifier. | | `feedKey` | path | Yes | string | Client-recognized feed key. The NBA feed is pulse. | | `atAction` | query | No | integer | Replay: keep only items whose content.actionNumber (the NBA play-by-play actionNumber they attach to) is at or before this value. Sample games and public live feeds; the Portland version 1 fixture returns 400. | | `asOf` | query | No | string | Replay: keep only items whose publishedAt is at or before this RFC 3339 date-time, which must carry a time zone (encode + as %2B). Combined with atAction, an item must satisfy both. Sample games and public live feeds; the Portland version 1 fixture returns 400. | | `If-None-Match` | header | No | string | | | Status | Meaning | Response headers | | ------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | `200` | The GET headers. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | | `304` | The snapshot has not changed. | `ETag`; `Access-Control-Allow-Origin`; `Access-Control-Expose-Headers` | | `400` | Invalid replay parameter. | | | `404` | Unknown fixture or feed, or a feed the deployment does not serve publicly. | | **Complete OpenAPI operation** ```json { "operationId": "headNbaAiInsightsFixtureFeed", "summary": "The snapshot headers without a body", "parameters": [ { "$ref": "#/components/parameters/FixtureId" }, { "$ref": "#/components/parameters/FeedKey" }, { "$ref": "#/components/parameters/AtAction" }, { "$ref": "#/components/parameters/AsOf" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "responses": { "200": { "description": "The GET headers.", "headers": { "ETag": { "$ref": "#/components/headers/ETag" }, "Access-Control-Allow-Origin": { "$ref": "#/components/headers/AccessControlAllowOrigin" }, "Access-Control-Expose-Headers": { "$ref": "#/components/headers/AccessControlExposeHeaders" } } }, "304": { "$ref": "#/components/responses/NotModified" }, "400": { "description": "Invalid replay parameter." }, "404": { "description": "Unknown fixture or feed, or a feed the deployment does not serve publicly." } } } ``` ### OPTIONS — CORS preflight [#options--cors-preflight-1] | Parameter | Location | Required | Format | Description | | ----------- | -------- | -------- | ------ | ----------------------------------------------------------------------- | | `fixtureId` | path | Yes | string | NBA game ID used as the integrating client's stable fixture identifier. | | `feedKey` | path | Yes | string | Client-recognized feed key. The NBA feed is pulse. | | Status | Meaning | Response headers | | ------ | ------------------------ | --------------------------------------------------------------------------------------------- | | `204` | CORS preflight accepted. | `Access-Control-Allow-Origin`; `Access-Control-Allow-Methods`; `Access-Control-Allow-Headers` | **Complete OpenAPI operation** ```json { "operationId": "preflightNbaAiInsightsFixtureFeed", "summary": "CORS preflight", "parameters": [ { "$ref": "#/components/parameters/FixtureId" }, { "$ref": "#/components/parameters/FeedKey" } ], "responses": { "204": { "$ref": "#/components/responses/Preflight" } } } ``` ## Other public resources [#other-public-resources] These GET routes also support HEAD. They are served alongside the resource paths in the OpenAPI document. | Path | Response | | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- | | [/v1/openapi.json](https://api.live.storyos.ai/v1/openapi.json) | NBA integration OpenAPI document | | [/v1/content-feed.schema.json](https://api.live.storyos.ai/v1/content-feed.schema.json) | Generic feed and item JSON Schema | | [/v1/nba-ai-insights-feed.schema.json](https://api.live.storyos.ai/v1/nba-ai-insights-feed.schema.json) | NBA definitions and structures | | `/v1/fixtures/0022501147/assets/{file}` | Shot-chart SVG assets referenced by the Portland feed | For full response structures, read [Item types](/markdown/item-types.md). The [error guide](/markdown/errors.md) also covers unexpected server failures.