Listening

The engine does not generate or transcribe audio. The client provides audioUrl, transcript and questions already resolved (e.g. by running its own Speech-to-Text pipeline before calling this API — see Recommended STT Integration).

Content shape

{
  "audioUrl": "https://cdn.example.com/audio/lesson-12.mp3",
  "transcript": "John lives in London and works as a teacher.",
  "title": "Where does John live?",
  "durationSeconds": 34,
  "questions": [
    {
      "id": "q1",
      "type": "multiple_choice",
      "question": "Where does John live?",
      "options": ["Paris", "London", "Madrid"],
      "correctAnswer": "London"
    }
  ]
}

title and durationSeconds are optional. Only multiple_choice questions are supported today.

Create (validate + sanitize)

POST /exercises

{
  "type": "listening_multiple_choice",
  "content": { "...as above, with correctAnswer..." }
}

Response (correctAnswer removed from every question — the client must keep the original content to evaluate later):

{
  "id": "generated-uuid",
  "type": "listening_multiple_choice",
  "group": "LISTENING",
  "subgroup": "MULTIPLE_CHOICE",
  "content": {
    "audioUrl": "https://cdn.example.com/audio/lesson-12.mp3",
    "transcript": "John lives in London and works as a teacher.",
    "title": "Where does John live?",
    "durationSeconds": 34,
    "questions": [
      { "id": "q1", "type": "multiple_choice", "question": "Where does John live?", "options": ["Paris", "London", "Madrid"] }
    ]
  },
  "metadata": { "difficulty": "easy", "tags": [], "language": "en" }
}

Returns 400 if audioUrl is missing/invalid, transcript is empty, questions is empty, a correctAnswer isn’t one of its options, or question ids/options are duplicated.

Evaluate

POST /exercises/evaluate

The engine is stateless today — it doesn’t store the exercise you created above. Resend the full content, including correctAnswer:

{
  "exerciseId": "ex_001",
  "area": "listening",
  "type": "listening_multiple_choice",
  "content": { "...full ListeningContent, with correctAnswer..." },
  "answer": "{\"q1\":\"London\"}"
}

{
  "correct": true,
  "score": 10,
  "feedback": "Correct! You understood the audio.",
  "metadata": { "area": "listening", "type": "listening_multiple_choice" }
}

See ADR 0001 for why the contract works this way today and how it’s expected to evolve.