Yeni bir kullanıcı hesabı oluşturur. Başarılı kayıt sonrası otomatik olarak token döner.

Email ve şifre ile giriş yapar, başarılı olursa Bearer token döner. Bu token diğer korumalı endpoint'lerde kullanılır.

{
  "success": true,
  "message": "Giriş başarılı",
  "token": "1|abc123...",
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com"
  }
}

Giriş yapmış kullanıcının bilgilerini döner. Token gerektirir.

Mevcut token'ı iptal eder ve kullanıcıyı çıkış yaptırır.

Şifre sıfırlama e-postası gönderir.

Token ile şifre sıfırlama işlemini tamamlar.

Aktif onboarding flow'u ve tüm adımlarını döner. Kullanıcının mevcut durumunu ve tamamlanan adımları içerir.

Tüm onboarding adımlarını cevaplanma durumuyla birlikte listeler. Bu endpoint ile tüm step'leri tek seferde alabilir ve next'e gerek kalmadan flow'u gösterebilirsiniz.

Kullanıcının tamamlaması gereken bir sonraki onboarding adımını döner. Cevaplanan step'ten sonraki ilk cevaplanmamış step'i döndürür.

Belirli bir onboarding adımı için kullanıcının cevabını kaydeder.

Onboarding sürecini tamamlar ve kullanıcıyı ana uygulamaya yönlendirir.

Kullanıcının günlük girişini kaydeder. Streak bilgisi ve bonus XP döner.

Belirli bir eylem için puan kazandırır. Aksiyon tipine göre puan miktarı değişir.

Kullanıcının mevcut puan durumunu, seviye bilgisini ve streak verisini döner.

Kullanıcının puan kazanma geçmişini sayfalı olarak döner.

Tüm avatar kategorilerini ve içerdikleri parçaları döner. Her parçanın fiyatı, kilit durumu ve kullanıcının sahip olup olmadığı bilgisi içerir.

Kullanıcının mevcut avatar konfigürasyonunu döner. Seçili parçalar ve sahip olunan tüm parçalar listelenir.

Avatar konfigürasyonunu kaydeder. Yeni parça seçimi veya satın alma işlemi yapar. Kullanıcının sahip olmadığı parça seçilirse otomatik satın alma yapılır.

Kullanıcının alabileceği aktif placement testlerini listeler. Daha önce tamamlanmış ve devam eden testler bilgisi içerir.

Yeni bir placement test oturumu başlatır veya devam eden oturumu döner. İlk soru ile birlikte oturum bilgisi döner.

Mevcut soruya cevap gönderir. Adaptif sistem sonraki soruyu belirler. Cevap doğruluğuna göre zorluk seviyesi ayarlanır.

Placement testini tamamlar ve sonuçları hesaplar. Belirlenen seviye kullanıcı profiline kaydedilir.

Kullanıcının placement test sonucu belirlenen seviyesini döner. Test tamamlanmamışsa null döner.

Öğrencinin kayıtlı olduğu sınıfları listeler.

Öğrencinin erişebileceği dersleri listeler.

Belirli bir dersin detay bilgilerini döner.

Öğrencinin atanmış sınavlarını listeler.

Sınav detay bilgilerini döner.

Sınav cevaplarını gönderir.

Öğrencinin genel ilerleme bilgilerini döner.

Öğrencinin puan bilgilerini döner.

Öğrencinin kazandığı rozetleri listeler.

Sınıf veya okul bazlı liderlik tablosunu döner.

Konuşma pratiğinde kullanılabilir TTS seslerinin listesini döner. Kadın ve erkek ses seçenekleri voice_id, isim, açıklama ve speaker_id ile döner.

Giriş yapan kullanıcının sınıfı ve İngilizce seviyesine göre konuşma senaryolarını döner. Listeden seçilen senaryonun id değeri ile POST /practice/start çağrılarak konuşma başlatılır.

Senaryo tabanlı konuşma oturumu başlatır. AI'nın rolü, konu, kelime hedefleri ve gramer hedefleri belirlenir. session_id döner, sonraki mesajlar için bu ID kullanılır.

{
  "partner_name": "Sarah",
  "llm_role": "friendly coffee shop barista",
  "total_steps": 8,
  "topic": "ordering coffee",
  "details": "Focus on polite expressions",
  "vocabulary": ["latte", "espresso", "pastry"],
  "target_grammar": ["Would like", "Present Perfect"],
  "difficulty": "B1",
  "voice_gender": "female",
  "speech_rate": 1.0,
  "enable_tts": true
}

{
  "session_id": "a1b2c3d4e5f6g7h8",
  "opening_message": "Hi there! Welcome to our coffee shop. What can I get for you today?",
  "partner_name": "Sarah",
  "total_steps": 8,
  "audio_base64": "UklGRi4AAAB... (base64 WAV veya null)",
  "voice_id": "female_1"
}

Devam eden konuşmada mesaj gönderir ve AI yanıtını alır. Adım sayacı ve bitiş durumu döner. is_done: true olduğunda konuşma tamamlanmıştır.

{
  "session_id": "a1b2c3d4e5f6g7h8",
  "user_message": "Hi! I would like a latte please."
}

{
  "session_id": "a1b2c3d4e5f6g7h8",
  "ai_message": "Sure! Would you like a regular or large latte?",
  "current_step": 2,
  "total_steps": 8,
  "remaining_steps": 6,
  "is_done": false,
  "audio_base64": "UklGRi4AAAB... (base64 WAV veya null)"
}

Konuşma oturumunu sonlandırır ve özet rapor döner.

Kullanıcının geçmiş konuşmalarını listeler. Filtreleme yapılabilir.

Belirli bir konuşmanın detaylarını ve tüm mesajlarını getirir.

AI ve kullanıcı mesajlarını alır, sadece kullanıcı mesajlarını analiz eder. Tek bir LLM çağrısıyla tüm mesajlar analiz edilir. Senaryo tabanlı pratik için topic ve details alanları mevcuttur.

{
  "ai_transcript": [
    "Hi! Welcome to our coffee shop. What can I get for you today?",
    "Sure! Would you like a regular or large latte?",
    "Great choice! That will be $4.50."
  ],
  "user_transcript": [
    "Hi! I would like a latte please.",
    "I want large one.",
    "Here you go. I buyed a cookie too."
  ],
  "difficulty": "B1",
  "topic": "ordering coffee",
  "details": "Focus on polite expressions"
}

{
  "reviews": [
    {
      "id": 1,
      "original": "Hi! I would like a latte please.",
      "annotated": "Hi! I would like a latte please.",
      "corrected": "Hi! I would like a latte please.",
      "errors": [],
      "has_errors": false
    },
    {
      "id": 2,
      "original": "I want large one.",
      "annotated": "I want [red]large[red] one.",
      "corrected": "I want a large one.",
      "errors": ["Missing article: 'a' before 'large one'"],
      "has_errors": true
    },
    {
      "id": 3,
      "original": "Here you go. I buyed a cookie too.",
      "annotated": "Here you go. I [red]buyed[red] a cookie too.",
      "corrected": "Here you go. I bought a cookie too.",
      "errors": ["Wrong verb form: 'buyed' should be 'bought' (irregular past)"],
      "has_errors": true
    }
  ],
  "overall_feedback": "Good basic communication with minor grammar errors.",
  "total_messages": 3,
  "messages_with_errors": 2
}

Zaman tabanlı serbest konuşma oturumu başlatır. Konu belirlenmez, AI öğretmen olarak serbest konuşma başlatır.

{
  "duration_minutes": 15,
  "difficulty": "B1",
  "voice_gender": "female",
  "speech_rate": 1.0,
  "enable_tts": true
}

{
  "session_id": "f8e7d6c5b4a39281",
  "opening_message": "Hello! Welcome to our practice session. How are you today?",
  "duration_minutes": 15,
  "remaining_seconds": 900,
  "audio_base64": "UklGRi4AAAB... (base64 WAV veya null)",
  "voice_id": "female_1"
}

Devam eden serbest konuşmada mesaj gönderir. remaining_seconds ile geri sayım takip edilir. is_done: true olduğunda oturum bitmiştir.

{
  "session_id": "f8e7d6c5b4a39281",
  "user_message": "I like traveling. Last summer I go to Italy."
}

{
  "session_id": "f8e7d6c5b4a39281",
  "ai_message": "How exciting! Just a small note - we say 'I went to Italy'...",
  "remaining_seconds": 840,
  "is_done": false,
  "audio_base64": "UklGRi4AAAB..."
}

Mesaj göndermeden oturum zamanlayıcısını kontrol eder. UI geri sayımı için idealdir.

{
  "session_id": "f8e7d6c5b4a39281",
  "duration_minutes": 15,
  "elapsed_seconds": 120,
  "remaining_seconds": 780,
  "is_done": false,
  "message_count": 4
}

Serbest konuşma pratiğinde kullanılabilir TTS seslerinin listesini döner.

AI ve kullanıcı mesajlarını alır, sadece kullanıcı mesajlarını analiz eder. topic/details YOKTUR — serbest konuşma olduğu için bağlam sadece konuşma akışından çıkarılır.

{
  "ai_transcript": [
    "Hello! Welcome to our practice session. How are you today?",
    "That sounds lovely! What do you enjoy most about traveling?",
    "Italy has amazing food! What was your favorite dish there?"
  ],
  "user_transcript": [
    "I am fine, thank you. I like traveling very much.",
    "I enjoy to visit new places and meet new peoples.",
    "I eated pasta every day! It was very delicious."
  ],
  "difficulty": "B1"
}

{
  "reviews": [
    {
      "id": 1,
      "original": "I am fine, thank you. I like traveling very much.",
      "annotated": "I am fine, thank you. I like traveling very much.",
      "corrected": "I am fine, thank you. I like traveling very much.",
      "errors": [],
      "has_errors": false
    },
    {
      "id": 2,
      "original": "I enjoy to visit new places and meet new peoples.",
      "annotated": "I enjoy [red]to visit[red] new places and meet new [red]peoples[red].",
      "corrected": "I enjoy visiting new places and meeting new people.",
      "errors": [
        "Wrong verb form: 'enjoy to visit' should be 'enjoy visiting' (gerund)",
        "Wrong plural: 'peoples' should be 'people' (irregular plural)"
      ],
      "has_errors": true
    },
    {
      "id": 3,
      "original": "I eated pasta every day! It was very delicious.",
      "annotated": "I [red]eated[red] pasta every day! It was very delicious.",
      "corrected": "I ate pasta every day! It was very delicious.",
      "errors": [
        "Wrong verb form: 'eated' should be 'ate' (irregular past tense of 'eat')"
      ],
      "has_errors": true
    }
  ],
  "overall_feedback": "Good conversational skills with some verb form errors.",
  "total_messages": 3,
  "messages_with_errors": 2
}

Öğrencinin sınıflarına atanmış üniteleri, aktif sınavlarını ve eğitim programlarını tek bir yanıtta döner. Sınıf sekmesinin ana ekranı için kullanılır.

{
  "success": true,
  "data": {
    "units": [
      {
        "id": 1,
        "title": "Ünite 1: Greetings & Introductions",
        "description": "Tanışma ve selamlaşma kalıpları",
        "lessons_count": 5,
        "icon": "ph-handshake"
      }
    ],
    "active_exams": [
      {
        "assignment_id": 12,
        "exam": {
          "id": 4,
          "title": "Unit 1 Reading Quiz",
          "exam_type": "reading",
          "duration_minutes": 20,
          "total_questions": 10
        },
        "due_date": "2026-05-01T23:59:59+03:00"
      }
    ],
    "education": {
      "enrollments": [
        {
          "program_id": 1,
          "title": "Yaz Kampı A1",
          "description": "Başlangıç seviyesi ingilizce",
          "status": "in_progress",
          "completion_percent": 35
        }
      ],
      "available_programs": [
        { "id": 2, "title": "Kış Okulu A2", "description": "A2 seviyesine geçiş" }
      ]
    },
    "progress": {
      "total_sessions": 12,
      "completed_sessions": 7,
      "total_xp": 420,
      "completion_percent": 58
    }
  }
}

Öğrencinin kayıtlı olduğu sınıfları, sınıf seviyesi, okul ve dönem bilgileri ile döner.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "5-A Sınıfı",
      "grade_level": "5. Sınıf",
      "school": "Atatürk Ortaokulu",
      "term": "2026 Bahar",
      "enrolled_at": "2026-02-01T00:00:00.000000Z"
    }
  ]
}

Öğrencinin sınıflarına atanmış ünitelerdeki tüm aktif dersleri döner.

{
  "success": true,
  "data": [
    {
      "id": 1,
      "title": "Lesson 1: Hello & Nice to Meet You",
      "description": "Temel selamlaşma kalıpları",
      "duration_min": 30,
      "unit": "Ünite 1: Greetings & Introductions",
      "order": 1
    }
  ]
}

Bir dersin içeriklerini (Reading / Listening / Speaking / Writing / Practice / Sınav) birleşik olarak döner. contents altında her içerik tipi ayrı bir dizidir.

{
  "success": true,
  "data": {
    "id": 1,
    "title": "Lesson 1: Hello & Nice to Meet You",
    "description": "Temel selamlaşma kalıpları",
    "duration_min": 30,
    "unit": { "id": 1, "title": "Ünite 1: Greetings & Introductions" },
    "contents": {
      "reading": [ { "id": 10, "title": "Meeting New Friends", "difficulty": "A1" } ],
      "listening": [ { "id": 4, "title": "A Phone Call", "duration": 45 } ],
      "speaking": [ { "id": 2, "title": "Introduce Yourself" } ],
      "writing": [ { "id": 1, "title": "Write About Your Day" } ],
      "practice": [
        { "id": 3, "topic": "Meeting a Classmate", "cefr_level": "A1" }
      ],
      "exams": [ { "id": 4, "title": "Unit 1 Reading Quiz", "exam_type": "reading" } ]
    }
  }
}

Şu an açık olan ve öğrenciye atanmış sınavları listeler.

Gelecekte açılacak sınavları listeler (opens_at > now).

Tamamlanan veya süresi dolan sınavları listeler.

Yeni sınav oturumu oluşturur ve zamanlayıcıyı başlatır.

Sınav sorularını ve kalan süreyi döner. Doğru cevaplar gizlidir.

Soru bazlı otomatik kayıt (autosave). Süre dolduysa kabul edilmez.

Sınavı sonlandırır, otomatik puanlama yapar ve sonuç üretir.

Sınav sonuç detaylarını döner. show_result_immediately false ise 403 döner.

Speaking sınavlarında veya audio_response/open/essay sorularında ses dosyası yükler. Multipart form-data ile gönderilmeli. Önceki yükleme varsa silinir.

{
  "success": true,
  "data": {
    "file_id": 42,
    "file_url": "http://localhost:8001/storage/exam-audio/12/xyz.webm",
    "transcript": null,
    "duration_ms": 8200
  }
}

Writing sınavlarında veya essay/open sorularında uzun metin gönderir. analyze=true gönderilirse AI /writing/analyze ile ön değerlendirme yapılır ve sonuç cevap içine kaydedilir.

{
  "success": true,
  "data": {
    "answer_id": 17,
    "word_count": 142,
    "ai_analysis": {
      "overall_score": 78,
      "task_achievement": 80,
      "grammar": 75,
      "vocabulary": 82,
      "coherence": 74,
      "suggestions": ["Use more linking words...", "Vary sentence length..."],
      "corrected_version": "..."
    },
    "saved_at": "2026-04-16T17:24:00Z"
  }
}

Kullanıcının grade_level'ına uygun programları listeler.

Kullanıcıyı programa kaydeder ve ilerleme tablolarını başlatır.

Programın ünitelerini ve tamamlanma yüzdesini döner.

Ünitenin derslerini ve her ders için kilit durumunu döner.

Dersin içeriğini ve soru bankasını döner. Kilitliyse 403 döner.

Dersi tamamlandı olarak işaretler ve sonraki dersi/üniteyi açar.

Ders içindeki bir soruyu cevaplar.

Belirtilen ay için etkinlikleri gruplandırılmış olarak döner.

Belirtilen gün için etkinlikleri döner.

Bugünkü etkinlikleri döner.

Gelecek N gün içindeki etkinlikleri döner. Push bildirimi için kullanışlı.

Belirli bir etkinliğin detaylarını döner.

Kullanıcının bildirimlerini sayfalanmış olarak döner.

Okunmamış bildirim sayısını döner. Badge gösterimi için kullanılır.

Belirli bir bildirimi okundu olarak işaretler.

Tüm bildirimleri okundu olarak işaretler.

Bildirimler ve duyuruları birleşik akış olarak döner.

Kullanıcının bildirim tercihlerini döner.

Bildirim tercihlerini günceller.

Kullanıcının genel ilerleme özetini döner: toplam XP, seviye, streak, rozet sayısı.

Reading, Listening, Speaking, Writing modüllerinin yüzdelik ilerlemesini döner.

Kullanıcının kazandığı ve henüz kazanmadığı rozetleri listeler.

Kullanıcının XP kazanım geçmişini döner.

XP bazlı kullanıcı sıralamasını döner.

Günlük giriş kontrolü yapar, streak günceller ve XP verir.

Rozeti profilinde göster/gizle.

Kullanıcının profil bilgilerini döner.

Profil bilgilerini günceller.

Kullanıcının eğitim bilgilerini ve mevcut seçenekleri döner. Öğrenci kayıt sonrası eğitim bilgilerini toplamak için kullanılır.

Öğrenci kayıt olduktan sonra eğitim bilgilerini kaydeder veya günceller. Sadece öğrenciler için kullanılabilir.

Profil fotoğrafı yükler. Multipart form-data kullanılır.

Kullanıcı şifresini değiştirir. Mevcut token iptal edilir.

Kullanıcı emailini değiştirir. Yeni email için doğrulama gerekir.

Hesap güvenlik geçmişini döner (giriş, şifre değişikliği vb.).

Kullanıcı hesabını kalıcı olarak siler.

API hakkında genel bilgileri döner. Versiyon, desteklenen özellikler ve konfigürasyon bilgisi içerir.

Harici servislerin (OpenAI, ElevenLabs vb.) çalışma durumunu kontrol eder. Her servisin durumu ve yanıt süresi döner.

Tüm onboarding flow'larını listeler.

Yeni onboarding flow'u oluşturur.

Belirli bir flow'un detayını döner.

Flow'u aktif eder. Diğer aktif flow'lar deaktif edilir.

Flow'a ait adımları listeler.

Step'e ait seçenekleri listeler.