A ready-made clip sequence

GET/v1/feed

Returns a shuffled sequence of clips for a level, with one suggested focus word per clip. Use it when you want a scrollable feed without building your own selection logic.

The ordering is random per request. Pass a seed to make it reproducible, which is what pagination needs: the same seed with the returned nextCursor continues the same shuffle instead of reshuffling.

The feed carries no per-user state. Vocaflare does not know your users, so watch history, spaced repetition and personalisation stay on your side; the exclude parameter is how you feed that back in.

Parameters

Name	In	Type	Default	Required	Description
language	query	string	en	no	Language of the clips, as a two-letter code. Only languages listed by /corpus return results.
gloss	query	en | es | ja | pt | ru | tr | zh	en	no	Language for word meanings in the response. Falls back to English when a meaning is missing in the requested language.
level	query	A1 | A2 | B1 | B2 | C1 | C2		no	Target CEFR level. The focus word is picked one step above it, which is where a learner gains the most; the clips themselves are not filtered by level, because every clip in the corpus contains words from several levels.
exclude	query	string		no	Clip ids or video ids to leave out, comma separated. Up to 50.
seed	query	string		no	Makes the shuffle reproducible. Required for stable pagination.
limit	query	integer	20	no	Items per page.
cursor	query	string		no	The nextCursor of the previous page. Opaque; do not construct it yourself.

Response

Field	Type	Description
seed	string	The seed used. Echoed back when you did not send one, so the next page can reuse it.
items	object[]
items[].clip	object
items[].clip.clipId	string (uuid)	Stable Vocaflare id for the clip.
items[].clip.videoId	string	YouTube video id, for the embed.
items[].clip.title	string
items[].clip.language	string
items[].clip.level	A1 | A2 | B1 | B2 | C1 | C2	CEFR level assigned during screening.
items[].clip.durationS	integer	Clip length in seconds. The corpus holds clips up to 180 s.
items[].clip.channel	object
items[].clip.embedUrl	string	Ready-to-use embed URL. Playback happens in the caller's player.
items[].clip.watchUrl	string	Canonical watch URL, for the required attribution link.
items[].focusWord	object	The word worth teaching in this clip at the requested level. Null when the clip has none in band.
items[].focusWord.word	string
items[].focusWord.wordId	integer
items[].focusWord.level	A1 | A2 | B1 | B2 | C1 | C2	CEFR level assigned during screening.
items[].focusWord.meaning	string
items[].focusWord.tStart	number
nextCursor	string

Errors

Status	Code	When
401	invalid_key	The key is missing, unknown or disabled.
429	rate_limited	Too many requests, or the plan quota is spent. Retry-After carries the wait in seconds.

Example

curl https://clips.vocaflare.com/v1/feed \
  -H "Authorization: Bearer $VOCAFLARE_API_KEY"

{
  "seed": "6f1c2d",
  "items": [
    {
      "clip": {
        "clipId": "0f2a6c1e-88d7-4f0a-9f0b-1b7a2c3d4e5f",
        "videoId": "FinOIdu21XA",
        "title": "How to sound natural when you say 'receive'",
        "language": "en",
        "level": "B1",
        "durationS": 47,
        "channel": {
          "id": "UCxxxxxxxxxxxxxxxxxxxxxx",
          "name": "BBC Learning English"
        },
        "embedUrl": "https://www.youtube.com/embed/FinOIdu21XA?playsinline=1",
        "watchUrl": "https://www.youtube.com/watch?v=FinOIdu21XA"
      },
      "focusWord": {
        "word": "receive",
        "wordId": 4127,
        "level": "B1",
        "meaning": "almak",
        "tStart": 12.34
      }
    }
  ],
  "nextCursor": "eyJzIjoiNmYxYzJkIiwibyI6MTB9"
}