Topics in the corpus

GET/v1/topics

Lists every topic with how many clips carry it, broken down by CEFR level. Use it to see whether the corpus covers what your learners care about before you build a filter around it, and to decide which topics have enough beginner material.

Needs a key. /corpus gives the headline numbers without one; this endpoint maps the corpus in detail, which is for customers rather than for everyone.

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.

Response

Field	Type	Description
language	string
topics	object[]
topics[].topic	everyday | food | travel | sport | science | business | technology | entertainment | health | learning | other	What the clip is about. One label per clip, chosen from a fixed list so filters stay stable; other is used when nothing else fits. Topic and level are not independent: food, everyday and travel skew to the easier levels, science and business to the harder ones.
topics[].clips	integer	Clips carrying this topic in the requested language.
topics[].byLevel	object	Clip count per CEFR level, so a caller can see whether a topic has beginner material.
updatedAt	string (ISO 8601)

Errors

Status	Code	When
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/topics \
  -H "Authorization: Bearer $VOCAFLARE_API_KEY"

{
  "language": "en",
  "topics": [
    {
      "topic": "food",
      "clips": 151,
      "byLevel": {
        "A1": 2,
        "A2": 11,
        "B1": 123,
        "B2": 15
      }
    },
    {
      "topic": "science",
      "clips": 202,
      "byLevel": {
        "A2": 4,
        "B1": 53,
        "B2": 104,
        "C1": 41
      }
    }
  ],
  "updatedAt": "2026-09-20T00:40:00Z"
}