Vocabulary Endpoints

Access 8,242 German vocabulary words organized by CEFR level (A1-C1).

GET/vocab

Get vocabulary words filtered by CEFR level with pagination support.

Authentication

X-API-Key: demo-key-12345

Parameters

Parameter	Type	Required	Description
level	string	Required	CEFR level: a1, a2, b1, b2, or c1
limit	integer	Optional	Max results (1-500). Default: 100
offset	integer	Optional	Skip N results for pagination. Default: 0

Vocabulary by Level

834

1,408

2,000

Request Example

cURL

curl -X GET "https://german-language.onrender.com/vocab?level=a1&limit=10&offset=0" \
  -H "X-API-Key: demo-key-12345"

Response

200 OK

{
  "level": "A1",
  "total": 834,
  "returned": 10,
  "offset": 0,
  "data": [
    {
      "german": "frei",
      "english": "free",
      "all_translations": "free, unenslaved, unimprisoned",
      "gender": "",
      "pos": "adjective",
      "frequency_rank": 1,
      "example_de": "Die Gedanken sind frei.",
      "example_en": "Thought is free."
    },
    {
      "german": "September",
      "english": "September",
      "all_translations": "September",
      "gender": "der",
      "pos": "noun",
      "frequency_rank": 3,
      "example_de": "Sie blieben bis September in Rom.",
      "example_en": "They stayed in Rome till September."
    }
    // ... more entries
  ]
}

Vocabulary Entry Object

Field	Type	Description
german	string	German word
english	string	Primary English translation
all_translations	string	All possible translations
gender	string	Grammatical gender: der, die, das, or empty
pos	string	Part of speech (noun, verb, adjective, etc.)
frequency_rank	integer	Word frequency ranking within the level
example_de	string	German example sentence
example_en	string	English translation of example

GET/vocab/search

Search vocabulary by German or English word across all CEFR levels.

Search Parameters

Parameter	Type	Required	Description
q	string	Required	Search term (min 1 character)
level	string	Optional	Filter by CEFR level: a1, a2, b1, b2, c1
limit	integer	Optional	Max results (1-200). Default: 50

Search Request Example

cURL

# Search for "haus" across all levels
curl -X GET "https://german-language.onrender.com/vocab/search?q=haus&limit=10" \
  -H "X-API-Key: demo-key-12345"

# Search for "house" in A1 level only
curl -X GET "https://german-language.onrender.com/vocab/search?q=house&level=a1" \
  -H "X-API-Key: demo-key-12345"

Search Response

200 OK

{
  "query": "haus",
  "level_filter": null,
  "count": 15,
  "data": [
    {
      "german": "Haus",
      "english": "house",
      "all_translations": "house, home, building",
      "gender": "das",
      "pos": "noun",
      "frequency_rank": 45,
      "example_de": "Das Haus ist groß.",
      "example_en": "The house is big.",
      "level": "A1"
    },
    {
      "german": "Hausaufgabe",
      "english": "homework",
      "gender": "die",
      "pos": "noun",
      "level": "A2"
    }
    // ... more results
  ]
}

Search Notes

• Search is case-insensitive
• Matches partial words (e.g., "haus" matches "Hausaufgabe")
• Searches both German and English fields
• Results include the CEFR level in the response

Error Responses

400 Bad Request

{
  "detail": "Invalid level: x5. Use: a1, a2, b1, b2, c1"
}

401 Unauthorized

{
  "detail": "Invalid API key. Get a key at /register (coming soon)"
}

Try It Out

Test these endpoints in the API Playground.