Caching

The index is rebuilt at most once a day, so nearly every response is safe to reuse for hours. Responses carry Cache-Control and ETag, and both are worth honouring.

What changes when

Data	Changes	Suggested cache
Clip metadata	Only if the source video is removed	Days
Transcript	Never, for a given clip	Days, or store it
Word to clips	When the daily run adds clips for that word	Hours
Feed	Every request, by design	Do not cache
Corpus stats	Daily	An hour

Conditional requests

Keep the ETag you received and send it back:

curl "https://clips.vocaflare.com/v1/clips/FinOIdu21XA/transcript" \
  -H "Authorization: Bearer $VOCAFLARE_API_KEY" \
  -H 'If-None-Match: "8f3c2a1"'

A 304 costs you no quota and no bandwidth.

Store what is immutable

Transcripts and clip metadata do not change. Fetching one once, storing it next to your own content, and never asking again is the cheapest integration and the fastest one for your users. The only reason to refetch is a clip disappearing from the source platform.

Dead clips

Source videos get deleted or made private by their uploaders. We drop them from the index when a health check notices, but your stored copy will not know. Handle a player error by skipping to the next clip rather than showing a broken frame, and refresh stored clip ids periodically.