Polling and caching
Revalidate with ETags and keep your state consistent.
Contact Storyteller to agree a polling interval for your integration. No client polling cadence or delivery SLA is specified by the current read API.
Conditional reads
JSON responses carry an ETag. Keep its exact value, including quotes, and send it as If-None-Match on the next request to the same feed and replay query. When the representation is unchanged, the API returns 304 Not Modified with no body.
# Run both calls in the same shell. The second should return 304 with no body.
url='https://api.live.storyos.ai/v1/fixtures/0042500401/feeds/pulse'
etag=$(curl --fail --silent --show-error --head "$url" | \
awk 'tolower($1) == "etag:" {sub(/\r$/, "", $2); print $2}')
curl --silent --show-error --include --header "If-None-Match: $etag" "$url"Handle 304 before parsing JSON. It means your previous snapshot remains current, so it must not clear displayed items. An ETag is an opaque validator; do not compute revisions or timing from it.
Public and live response caching
| Response | Cache-Control | How to use it |
|---|---|---|
| Public JSON sample | public, max-age=0, must-revalidate | Revalidate before reusing the HTTP representation. |
| Live snapshot | no-store | Do not store the HTTP response in shared caches. Maintain your application’s prior integration state and ETag for conditional requests. |
| Errors | no-store | Handle the failure while retaining the last valid application snapshot. |
The same cache policy and ETag are returned on an unchanged conditional read. Weak validators, comma-separated lists and * are accepted by If-None-Match; using the exact returned tag is the simplest option.
Bounded polling examples
The JavaScript and Python examples make two reads. They replace state only after a successful full JSON response and preserve it on 304. Schedule further reads at your agreed interval. Avoid overlapping requests that could let an older response overwrite a newer snapshot.