Sentences Endpoints

Access 2,300 German-English sentence pairs with CEFR level tagging, grammar features, and topics.

GET/sentences

Get example sentences with optional CEFR level filtering and pagination.

Authentication

X-API-Key: demo-key-12345

Parameters

Parameter	Type	Required	Description
level	string	Optional	Filter by CEFR level: A1, A2, B1, B2, C1
limit	integer	Optional	Max results (1-200). Default: 50
offset	integer	Optional	Skip N results for pagination. Default: 0

Sentences by CEFR Level

282

14.1%

702

35.1%

586

29.3%

402

20.1%

1.3%

Request Examples

Get All Sentences

curl -X GET "https://german-language.onrender.com/sentences?limit=10" \
  -H "X-API-Key: demo-key-12345"

Filter by CEFR Level

# Get A1 sentences (beginner)
curl -X GET "https://german-language.onrender.com/sentences?level=A1&limit=10" \
  -H "X-API-Key: demo-key-12345"

# Get B2 sentences (upper-intermediate)
curl -X GET "https://german-language.onrender.com/sentences?level=B2&limit=10" \
  -H "X-API-Key: demo-key-12345"

Response

200 OK

{
  "level_filter": "A1",
  "total": 282,
  "returned": 10,
  "offset": 0,
  "data": [
    {
      "id": 1,
      "sentence_de": "Nein, ich weiß es nicht.",
      "sentence_en": "No, I don't know.",
      "cefr_level": "A1",
      "cefr_scores": {
        "vocabulary": 1.0,
        "grammar": 1.0,
        "complexity": 1.8
      },
      "word_count": 5,
      "clause_count": 2,
      "grammar_features": ["negation_nicht", "personal_pronoun"],
      "topic": "general",
      "register": "neutral",
      "source": "tatoeba",
      "license_tag": "CC-BY-2.0-FR"
    },
    {
      "id": 45,
      "sentence_de": "Das Haus ist groß.",
      "sentence_en": "The house is big.",
      "cefr_level": "A1",
      "word_count": 4,
      "clause_count": 1,
      "grammar_features": ["definite_article"],
      "topic": "housing"
    }
    // ... more entries
  ]
}

Response Schema

Sentence Object

Field	Type	Description
id	integer	Unique sentence identifier
sentence_de	string	German sentence
sentence_en	string	English translation
cefr_level	string	CEFR level: A1, A2, B1, B2, C1
cefr_scores	object	Breakdown: vocabulary, grammar, complexity scores
word_count	integer	Number of words in the German sentence
clause_count	integer	Number of clauses
grammar_features	array	Detected grammar features
topic	string	Topic category (e.g., "daily_life", "travel")
register	string	Formality: "formal", "neutral", "informal"

Available Topics

communication

daily_life

education

time

travel

nature

culture

family

work

shopping

emotions

hobbies

health

food_drink

general

housing

GET/sentences/random

Get random sentences for practice and quizzes. Great for flashcards and translation exercises.

Parameters

Parameter	Type	Required	Description
level	string	Optional	Filter by CEFR level: A1, A2, B1, B2, C1
count	integer	Optional	Number of random sentences (1-50). Default: 10

Request Examples

cURL

# Get 5 random sentences from any level
curl -X GET "https://german-language.onrender.com/sentences/random?count=5" \
  -H "X-API-Key: demo-key-12345"

# Get 10 random A1 sentences for beginners
curl -X GET "https://german-language.onrender.com/sentences/random?level=A1&count=10" \
  -H "X-API-Key: demo-key-12345"

Response

200 OK

{
  "level_filter": "A1",
  "count": 5,
  "data": [
    {
      "id": 234,
      "sentence_de": "Ich trinke Wasser.",
      "sentence_en": "I drink water.",
      "cefr_level": "A1",
      "word_count": 3,
      "grammar_features": ["personal_pronoun"],
      "topic": "food_drink"
    },
    {
      "id": 89,
      "sentence_de": "Wie heißen Sie?",
      "sentence_en": "What is your name?",
      "cefr_level": "A1",
      "word_count": 3,
      "grammar_features": ["question", "formal_Sie"],
      "topic": "communication"
    }
    // ... 3 more random sentences
  ]
}

Use Cases

🎯 Translation Quizzes

Show German sentence, ask user for English translation. Compare with sentence_en.

📝 Fill-in-the-Blank

Remove a word from sentence_de and create cloze exercises.

🔊 Reading Practice

Display sentences by difficulty level for graded reading practice.

📊 Grammar Focus

Filter by grammar_features to target specific structures.

Error Responses

400 Bad Request

{
  "detail": "Invalid level: X5"
}

401 Unauthorized

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

Try It Out

Test these endpoints in the API Playground.