API Dokümantasyonu

Genel Bakış

Base URL: https://www.xlyazilim.com/api/v1
Tüm API istekleri bu base URL üzerinden yapılmalıdır.

Hızlı Başlangıç

1. Kayıt Ol

POST /auth/register ile yeni hesap oluşturun.

Detaylı bilgi →

2. Giriş Yap

POST /auth/login ile token alın.

Detaylı bilgi →

3. Token Kullan

Authorization header'a Bearer token ekleyin.

Detaylı bilgi →

Kimlik Doğrulama

API, Laravel Sanctum tabanlı token authentication kullanır. Korumalı endpoint'lere erişmek için her istekte token gönderilmelidir.

HTTP Header

Authorization: Bearer YOUR_TOKEN_HERE

Önemli: Token'ı güvenli bir şekilde saklayın. Her oturum için yeni token alınmalıdır. Çıkış yapıldığında token geçersiz olur.

Hata Kodları

API standart HTTP durum kodlarını kullanır. Hata durumunda detaylı mesaj döner.

Kod	Durum	Açıklama
200	OK	İstek başarılı
201	Created	Kaynak başarıyla oluşturuldu
400	Bad Request	Geçersiz istek formatı
401	Unauthorized	Kimlik doğrulama gerekli veya token geçersiz
403	Forbidden	Bu işlem için yetkiniz yok
404	Not Found	Kaynak bulunamadı
422	Validation Error	Doğrulama hatası (detaylar response'da)
429	Too Many Requests	Rate limit aşıldı
500	Server Error	Sunucu hatası

                Örnek Hata Response
            

                {
  "success": false,
  "message": "Validation failed",
  "errors": {
    "email": ["Email alanı gereklidir."],
    "password": ["Şifre en az 8 karakter olmalıdır."]
  }
}
            

Kimlik Doğrulama (Auth)

6 Endpoint

Kullanıcı kayıt, giriş, çıkış ve şifre işlemleri için kullanılan endpoint'ler. Token tabanlı kimlik doğrulama (Laravel Sanctum) kullanılmaktadır.

POST /auth/register Public Yeni Kullanıcı Kaydı

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

Request Body

Parametre	Tip	Açıklama
name Zorunlu	string	Kullanıcının tam adı (min: 2)
email Zorunlu	string	Geçerli ve benzersiz email adresi
password Zorunlu	string	Şifre (min: 8 karakter)
password_confirmation Zorunlu	string	Şifre tekrarı

Test Et

POST /auth/login Public Kullanıcı Girişi

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

Request Body

Parametre	Tip	Açıklama
email Zorunlu	string	Kayıtlı email adresi
password Zorunlu	string	Kullanıcı şifresi

Test Et

                    Örnek Response
                

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

GET /auth/me Auth Mevcut Kullanıcı Bilgisi

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

Test Et

POST /auth/logout Auth Çıkış Yap

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

Test Et

POST /auth/forgot-password Public Şifremi Unuttum

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

Request Body

Parametre	Tip	Açıklama
email Zorunlu	string	Kayıtlı email adresi

Test Et

POST /auth/reset-password Public Şifre Sıfırla

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

Request Body

Parametre	Tip	Açıklama
token Zorunlu	string	E-posta ile gelen sıfırlama token'ı
email Zorunlu	string	Kullanıcı email adresi
password Zorunlu	string	Yeni şifre (min: 8)
password_confirmation Zorunlu	string	Yeni şifre tekrarı

Test Et

Onboarding

5 Endpoint

Yeni kullanıcıların ilk giriş akışını yöneten endpoint'ler. Kullanıcı tercihlerini toplar ve profili yapılandırır.

GET /onboarding/flow Auth Onboarding Flow Bilgisi

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

Test Et

GET /onboarding/steps Auth Tüm Adımları Listele

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.

Test Et

GET /onboarding/steps/next Auth Sonraki Adım

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.

Test Et

POST /onboarding/steps/{step_id}/answer Auth Adım Cevabı Gönder

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

URL Parametreleri

Parametre	Tip	Açıklama
step_id Zorunlu	integer	Onboarding adım ID'si

Request Body

Parametre	Tip	Açıklama
option_id Opsiyonel	integer	Seçilen seçenek ID'si (single/multiple choice için)
option_ids Opsiyonel	array	Seçilen seçenek ID'leri (multiple choice için)
answer Opsiyonel	string\|number\|boolean\|array	Cevap değeri (soru tipine göre: text, number, date, boolean, single_choice, multi_choice)

Test Et

POST /onboarding/complete Auth Onboarding Tamamla

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

Test Et

Engagement & Points

4 Endpoint

Günlük giriş, streak takibi ve puan kazanma sistemi için kullanılan endpoint'ler.

POST /engagement/daily-login Auth Günlük Giriş

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

Test Et

POST /points/earn Auth Puan Kazan

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

Request Body

Parametre	Tip	Açıklama
action Zorunlu	string	Aksiyon tipi (lesson_complete, quiz_pass, streak_bonus vb.)
reference_type Opsiyonel	string	Referans model tipi
reference_id Opsiyonel	integer	Referans model ID'si

Test Et

GET /points/me Auth Puan Bilgisi

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

Test Et

GET /points/history Auth Puan Geçmişi

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

Query Parametreleri

Parametre	Tip	Açıklama
page Opsiyonel	integer	Sayfa numarası (varsayılan: 1)
per_page Opsiyonel	integer	Sayfa başına kayıt (varsayılan: 20)

Test Et

Avatar Sistemi

3 Endpoint

Kullanıcı avatarı özelleştirme ve yönetim endpoint'leri. Kategorilere göre avatar parçaları satın alınabilir ve kombinlenebilir.

GET /avatar/catalog Auth Katalog

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.

Test Et

GET /avatar/me Auth Mevcut Avatar

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

Test Et

POST /avatar/save Auth Avatar Kaydet

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.

Request Body

Parametre	Tip	Açıklama
selections Zorunlu	object	Kategori bazlı seçimler {"hair": 5, "eyes": 2, ...}

Test Et

Seviye Belirleme (Placement)

5 Endpoint

Kullanıcının İngilizce seviyesini belirlemek için kullanılan test sistemi. Adaptif sorularla kullanıcının gerçek seviyesi tespit edilir.

GET /placement/active Auth Aktif Testler

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

Test Et

POST /placement/start Auth Test Başlat

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

Request Body

Parametre	Tip	Açıklama
test_id Zorunlu	integer	Test ID'si (aktif testlerden birini seçin)

Test Et

POST /placement/answer Auth Cevap Gönder

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

Request Body

Parametre	Tip	Açıklama
attempt_id Zorunlu	integer	Test attempt ID'si (start endpoint'inden alınır)
question_id Zorunlu	integer	Soru ID'si
answer Opsiyonel	string	Seçilen cevap (soru tipine göre değişir)

Test Et

POST /placement/finish Auth Testi Bitir

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

Request Body

Parametre	Tip	Açıklama
attempt_id Zorunlu	integer	Test attempt ID'si (start endpoint'inden alınır)

Test Et

GET /placement/level Auth Seviye Getir

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

Test Et

Öğrenci API (Student)

14 Endpoint

Öğrenci paneli için sınıf, ders, aktivite, sınav ve ilerleme bilgilerini yöneten endpoint'ler.

GET /student/classes Auth Sınıflarım

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

Test Et

GET /student/lessons Auth Derslerim

Öğrencinin erişebileceği dersleri listeler.

Test Et

GET /student/lessons/{lesson} Auth Ders Detayı

Belirli bir dersin detay bilgilerini döner.

Test Et

GET /student/activities Auth Aktivitelerim

Öğrencinin aktivitelerini listeler.

Test Et

GET /student/activities/{activity} Auth Aktivite Detayı

Belirli bir aktivitenin detayını döner.

Test Et

POST /student/activities/{activity}/complete Auth Aktivite Tamamla

Aktiviteyi tamamlandı olarak işaretler.

Test Et

GET /student/exams Auth Sınavlarım

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

Test Et

GET /student/exams/{exam} Auth Sınav Detayı

Sınav detay bilgilerini döner.

Test Et

POST /student/exams/{exam}/submit Auth Sınav Gönder

Sınav cevaplarını gönderir.

Test Et

GET /student/progress Auth İlerlemem

Öğrencinin genel ilerleme bilgilerini döner.

Test Et

GET /student/points Auth Puanlarım

Öğrencinin puan bilgilerini döner.

Test Et

GET /student/badges Auth Rozetlerim

Öğrencinin kazandığı rozetleri listeler.

Test Et

GET /student/leaderboard Auth Liderlik Tablosu

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

Test Et

GET /student/vocabulary Auth Kelime Setleri

Öğrencinin erişebileceği kelime setlerini listeler.

Test Et

Listening (Dinleme)

10 Endpoint

Dinleme içerikleri ve oturumlar için mobil API endpoint'leri. Grade + Level bazlı içerik sistemi ile çalışır.

Metadata Endpoint'leri: Voices, difficulty levels gibi endpoint'ler public'tir ve token gerektirmez.

AI İçerik Üretimi: Diyalog ve soru üretimi gibi AI endpoint'leri öğretmen panelinde bulunmaktadır.

GET /listening/voices Public Mevcut Sesler

Text-to-Speech için kullanılabilir seslerin listesini döner.

Test Et

GET /listening/difficulty-levels Public Zorluk Seviyeleri

Kullanılabilir zorluk seviyelerinin listesini döner.

Test Et

GET /listening/topic-suggestions Public Konu Önerileri

Dinleme içerikleri için önerilen konuların listesini döner.

Test Et

GET /listening/app/contents Auth İçerik Listesi

Kullanıcının grade ve level'ına göre filtrelenmiş dinleme içeriklerini listeler. Kilit durumu bilgisi içerir.

Test Et

GET /listening/app/contents/{id} Auth İçerik Detayı

Belirli bir dinleme içeriğinin detayını, diyalog satırlarını ve ses dosyalarını döner. İçerik kilitliyse 403 hatası döner.

URL Parametreleri

Parametre	Tip	Açıklama
id Zorunlu	integer	İçerik ID'si

Test Et

POST /listening/app/sessions/start Auth Oturum Başlat

Belirli bir içerik için dinleme oturumu başlatır. Devam eden oturum varsa onu döner.

Request Body

Parametre	Tip	Açıklama
content_id Zorunlu	integer	Dinleme içeriği ID'si

Test Et

GET /listening/app/sessions/{id}/questions Auth Oturum Soruları

Oturuma ait soruları döner. Doğru cevaplar gizlidir.

Test Et

POST /listening/app/sessions/{id}/answer Auth Cevap Gönder

Bir soru için cevap gönderir ve doğruluk durumunu döner.

Request Body

Parametre	Tip	Açıklama
question_id Zorunlu	integer	Soru ID'si
answer Zorunlu	mixed	Cevap (soru tipine göre string veya array)

Test Et

POST /listening/app/sessions/{id}/finish Auth Oturumu Bitir

Dinleme oturumunu tamamlar, skoru hesaplar ve XP kazandırır.

Test Et

POST /listening/app/sessions/{id}/progress Auth İlerleme Güncelle

Dinleme oturumunun ilerleme yüzdesini günceller.

Request Body

Parametre	Tip	Açıklama
progress_percent Zorunlu	integer	İlerleme yüzdesi (0-100)

Test Et

Reading (Okuma)

12 Endpoint

Okuma içerikleri ve oturumlar için mobil API endpoint'leri. Grade + Level bazlı içerik sistemi ile çalışır.

AI İçerik Üretimi: Metin ve soru üretimi gibi AI endpoint'leri öğretmen panelinde bulunmaktadır.

GET /reading/content-types Public İçerik Tipleri

Kullanılabilir okuma içerik tiplerinin listesini döner (article, story, dialogue vb.).

Test Et

GET /reading/writing-styles Public Yazım Stilleri

Kullanılabilir yazım stillerinin listesini döner (formal, informal, academic vb.).

Test Et

GET /reading/app/contents Auth İçerik Listesi

Kullanıcının grade ve level'ına göre filtrelenmiş okuma içeriklerini listeler.

Test Et

GET /reading/app/contents/{id} Auth İçerik Detayı

Belirli bir okuma içeriğinin detayını döner. Kilitliyse 403 hatası döner.

Test Et

GET /reading/app/contents/{id}/questions Auth İçerik Soruları

Belirli bir okuma içeriğine ait soruları döner. Her içeriğin MCQ, True/False, Fill Blank türünde soruları vardır.

Test Et

POST /reading/app/contents/{id}/questions/{questionId}/answer Auth Soruyu Cevapla

Bir içerik sorusuna cevap gönderir ve doğru/yanlış kontrolü yapar.

Request Body

Parametre	Tip	Açıklama
answer Zorunlu	string	Kullanıcının cevabı (MCQ için "A", "B", "C", "D" veya True/False için "True", "False")

Test Et

POST /reading/app/sessions/start Auth Oturum Başlat

Belirli bir içerik için okuma oturumu başlatır.

Request Body

Parametre	Tip	Açıklama
content_id Zorunlu	integer	Okuma içeriği ID'si

Test Et

POST /reading/app/sessions/{id}/answer Auth Cevap Gönder

Bir soru için cevap gönderir.

Test Et

POST /reading/app/sessions/{id}/finish Auth Oturumu Bitir

Okuma oturumunu tamamlar, skoru hesaplar ve XP kazandırır.

Test Et

GET /me/learning-profile Auth Öğrenme Profili

Kullanıcının öğrenme profilini, seviyesini ve aktif sınıf bilgisini döner.

Test Et

POST /reading/generate-fill-blank Auth Boşluk Doldurma Üret

Verilen metin için boşluk doldurma egzersizi üretir.

Request Body

Parametre	Tip	Açıklama
reading_text Zorunlu	string	Analiz edilecek okuma metni
question_count Zorunlu	integer	Oluşturulacak boşluk sayısı (1-20)
difficulty Opsiyonel	string	`beginner`, `elementary`, `intermediate`, `upper_intermediate`, `advanced`
additional_instructions Opsiyonel	string	Ek talimatlar

Test Et

Reading Text *

Question Count *

Difficulty (Opsiyonel)

Additional Instructions (Opsiyonel)

POST /reading/generate-sentence-builder Auth Cümle Kurma Üret

Karışık kelimelerden cümle kurma egzersizi üretir.

Request Body

Parametre	Tip	Açıklama
reading_text Zorunlu	string	Analiz edilecek okuma metni
question_count Zorunlu	integer	Oluşturulacak soru sayısı (1-10)
difficulty Zorunlu	string	`beginner`, `elementary`, `intermediate`, `upper_intermediate`, `advanced`
additional_instructions Opsiyonel	string	Ek talimatlar

Test Et

Reading Text *

Question Count *

Difficulty *

Additional Instructions (Opsiyonel)

POST /reading/generate-vocab-quiz Auth Kelime Quiz Üret

Verilen metinden kelime quizi üretir.

Request Body

Parametre	Tip	Açıklama
reading_text Zorunlu	string	Analiz edilecek okuma metni
word_count Zorunlu	integer	Oluşturulacak kelime sayısı (1-20)
difficulty Opsiyonel	string	`beginner`, `elementary`, `intermediate`, `upper_intermediate`, `advanced`
additional_instructions Opsiyonel	string	Ek talimatlar

Test Et

Reading Text *

Word Count *

Difficulty (Opsiyonel)

Additional Instructions (Opsiyonel)

POST /reading/generate-single-word-quiz Auth Tek Kelime Quiz Üret

Tek kelime için anlam/çeviri quizi üretir.

Test Et

POST /reading/app/sessions/{id}/progress Auth İlerleme Güncelle

Okuma oturumunun ilerleme yüzdesini günceller.

Test Et

POST /reading/app/sessions/{id}/generate-quiz Auth Quiz Oluştur

Oturumdaki içerik için otomatik quiz oluşturur.

Test Et

GET /reading/app/sessions/{id}/questions Auth Soruları Getir

Oturuma ait soruları döner.

Test Et

Speaking (Konuşma)

13 Endpoint

Konuşma pratikleri ve telaffuz egzersizleri için kullanılan endpoint'ler. Ses kaydı yükleme ve AI değerlendirme özelliklerini içerir.

GET /speaking/voices Public Mevcut Sesler

TTS için kullanılabilir seslerin listesini döner.

Test Et

GET /speaking/app/exercises Auth Egzersiz Listesi

Kullanıcının grade ve level'ına göre filtrelenmiş konuşma egzersizlerini listeler.

Test Et

GET /speaking/app/exercises/{id} Auth Egzersiz Detayı

Belirli bir konuşma egzersizinin detayını ve kelime/cümle listesini döner.

Test Et

POST /speaking/app/sessions/start Auth Oturum Başlat

Belirli bir egzersiz için konuşma oturumu başlatır.

Request Body

Parametre	Tip	Açıklama
exercise_id Zorunlu	integer	Konuşma egzersizi ID'si

Test Et

GET /speaking/app/items/{item_id}/pronunciation Auth Telaffuz Verisi Al

Belirli bir kelime/cümle için IPA, fonetik ve ses dosyası döner. Sonuçlar önbelleklenir.

Query Parametreleri

Parametre	Tip	Açıklama
voice_id Opsiyonel	string	Ses ID'si (varsayılan: female_1)
speed Opsiyonel	float	Hız (0.5 - 2.0, varsayılan: 1.0)

Test Et

POST /speaking/app/attempts/upload Auth Ses Kaydı Yükle

Kullanıcının ses kaydını yükler. Multipart form-data kullanılır.

Request Body (multipart/form-data)

Parametre	Tip	Açıklama
session_id Zorunlu	integer	Oturum ID'si
item_id Zorunlu	integer	Kelime/Cümle ID'si
audio_file Zorunlu	file	Ses dosyası (wav, m4a, mp3)

Bu endpoint dosya yüklemesi gerektirir ve tarayıcıdan test edilemez. Mobil uygulamadan veya Postman ile test edin.

POST /speaking/app/attempts/{attempt_id}/evaluate Auth Telaffuz Değerlendir

Yüklenen ses kaydını değerlendirir ve skor döner.

Request Body

Parametre	Tip	Açıklama
expected_text Zorunlu	string	Beklenen kelime/cümle
mode Opsiyonel	string	word veya sentence

Test Et

POST /speaking/app/sessions/{id}/finish Auth Oturumu Bitir

Konuşma oturumunu tamamlar, genel skoru hesaplar ve XP kazandırır.

Test Et

POST /speaking/word-pronunciation Auth AI Kelime Telaffuzu

Kelime listesi için IPA, fonetik ve ses dosyası üretir.

Request Body

Parametre	Tip	Açıklama
words Zorunlu	array	Kelime listesi
voice_id Opsiyonel	string	Ses ID'si

Test Et

GET /speaking/health Public Sağlık Durumu

Speaking servisinin sağlık durumunu kontrol eder.

Test Et

Writing (Yazma)

8 Endpoint

Yazma pratikleri ve AI destekli analiz için kullanılan endpoint'ler. Taslak kaydetme, gönderme ve detaylı analiz özellikleri içerir.

GET /writing/app/tasks Auth Görev Listesi

Kullanıcının grade ve level'ına göre filtrelenmiş yazma görevlerini listeler.

Query Parameters (Opsiyonel)

Parametre	Tip	Açıklama
level_id Opsiyonel	integer	Level band ID'sine göre filtrele
type Opsiyonel	string	Yazı türüne göre filtrele (email, essay, letter, report, story)

Test Et

GET /writing/app/tasks/{id} Auth Görev Detayı

Belirli bir yazma görevinin detayını, talimatları ve ipuçlarını döner.

Test Et

POST /writing/app/submissions/save-draft Auth Taslak Kaydet

Kullanıcının yazısını taslak olarak kaydeder. Aynı görev için birden fazla taslak oluşturulamaz.

Request Body

Parametre	Tip	Açıklama
task_id Zorunlu	integer	Yazma görevi ID'si
user_text Zorunlu	string	Kullanıcının yazdığı metin

Test Et

POST /writing/app/submissions/{id}/submit Auth Gönderi Yap

Taslağı final gönderim olarak işaretler. Gönderim sonrası düzenleme yapılamaz.

Test Et

POST /writing/app/submissions/{id}/analyze Auth AI ile Analiz Et

Gönderilen yazıyı AI ile analiz eder. Grammar, fluency, vocabulary ve structure skorları döner.

Test Et

GET /writing/app/submissions/{id}/result Auth Sonuç Getir

Analiz edilmiş gönderimin detaylı sonuçlarını döner. Güçlü yönler ve gelişim önerileri içerir.

Test Et

POST /writing/generate-task Auth AI ile Görev Oluştur

AI kullanarak yazma görevi oluşturur. Admin/Teacher panelinde kullanılır.

Request Body

Parametre	Tip	Açıklama
topic Zorunlu	string	Görev konusu (max 500 karakter)
task_type Zorunlu	string	Yazı tipi: `essay`, `email`, `letter`, `story`, `report`, `review`, `article`
difficulty Zorunlu	string	Zorluk seviyesi: `a1`, `a2`, `b1`, `b2`, `c1`, `c2`
word_count_min Opsiyonel	integer	Minimum kelime sayısı (min: 50)
word_count_max Opsiyonel	integer	Maksimum kelime sayısı (max: 2000)
focus_grammar Opsiyonel	array	Odaklanılacak dilbilgisi konuları. Örn: `["past_simple", "conditionals"]`
include_rubric Opsiyonel	boolean	Değerlendirme kriterleri eklensin mi?
include_sample Opsiyonel	boolean	Örnek yanıt eklensin mi?

Test Et

Topic *

Task Type *

Difficulty *

Word Count Min (Opsiyonel)

Word Count Max (Opsiyonel)

Include Rubric (Opsiyonel)

Include Sample (Opsiyonel)

POST /writing/analyze Auth AI Yazı Analizi

Verilen metni AI ile analiz eder. Grammar, vocabulary, coherence ve task achievement skorları döner.

Request Body

Parametre	Tip	Açıklama
task_instruction Zorunlu	string	Yazma görevinin talimatı
user_response Zorunlu	string	Analiz edilecek metin (min 10 karakter)
difficulty Zorunlu	string	`beginner`, `elementary`, `intermediate`, `upper_intermediate`, `advanced`
target_tense Opsiyonel	string	Hedef zaman: `past_simple`, `present_simple`, `future_simple`, vb.
target_vocabulary Opsiyonel	array	Hedef kelimeler. Örn: `["opportunity", "experience"]`
additional_details Opsiyonel	string	Ek talimatlar
tips Opsiyonel	array	Kullanıcıya verilecek ipuçları. Örn: `["Use formal language", "Include examples"]`

Test Et

Task Instruction *

User Response *

Difficulty *

Target Tense (Opsiyonel)

Target Vocabulary (JSON) (Opsiyonel)

Additional Details (Opsiyonel)

Tips (JSON) (Opsiyonel)

GET /writing/health Public Sağlık Durumu

Writing servisinin sağlık durumunu kontrol eder.

Test Et

Derslerim (Education)

8 Endpoint

Klasik eğitim omurgası: Program → Ünite → Ders → İçerik hiyerarşisi. Kilitli ilerleme sistemi ile çalışır - bir ders bitmeden sonraki açılmaz.

Kilit Mantığı: Kullanıcı programa kayıt olduğunda ilk ünitenin ilk dersi açık, diğerleri kilitlidir. Ders tamamlandıkça sıradaki içerikler otomatik açılır.

GET /education/app/programs Auth Program Listesi

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

Test Et

POST /education/app/programs/{id}/enroll Auth Programa Kayıt Ol

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

Test Et

GET /education/app/programs/{id} Auth Program Detayı

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

Test Et

GET /education/app/units/{id} Auth Ünite Detayı

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

Test Et

GET /education/app/lessons/{id} Auth Ders Detayı

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

Test Et

POST /education/app/lessons/{id}/complete Auth Ders Tamamla

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

Test Et

POST /education/app/lessons/{id}/answer Auth Soru Cevapla

Ders içindeki bir soruyu cevaplar.

Request Body

Parametre	Tip	Açıklama
question_id Zorunlu	integer	Soru ID'si
answer Zorunlu	mixed	Cevap

Test Et

Konular (Topics)

7 Endpoint

Konu bazlı içerik sistemi: Topic → Lesson → Unit hiyerarşisi. Serbest ilerleme sistemi - kullanıcı istediği konuyu seçip çalışabilir.

İlerleme Takibi: Kullanıcı herhangi bir konuyu açtığında ilerleme kaydı oluşturulur. Üniteler tamamlandıkça ders otomatik tamamlanır.

GET /topics/app Auth Konu Listesi

Tüm aktif konuları listeler. Her konu için ders sayısı ve ilerleme durumu döner.

Test Et

GET /topics/app/{id} Auth Konu Detayı

Belirli bir konunun detayını ve derslerini döner.

Test Et

GET /topics/app/lessons/{id} Auth Ders Detayı

Belirli bir dersin detayını ve ünitelerini döner.

Test Et

POST /topics/app/lessons/{id}/complete Auth Dersi Tamamla

Dersi manuel olarak tamamlandı olarak işaretler.

Test Et

GET /topics/app/units/{id} Auth Ünite Detayı

Belirli bir ünitenin içeriğini ve navigasyon bilgilerini döner.

Test Et

POST /topics/app/units/{id}/complete Auth Üniteyi Tamamla

Üniteyi tamamlandı olarak işaretler. Tüm üniteler tamamlanınca ders otomatik tamamlanır.

Test Et

GET /topics/app/progress Auth İlerleme Özeti

Kullanıcının tüm konulardaki ilerleme özetini döner.

Test Et

Sınavlarım (Exams)

9 Endpoint

Skill-based sınavlar: Reading, Listening, Speaking, Writing. Zamanlı sınav sistemi, otomatik değerlendirme ve manuel review desteği.

Zamanlayıcı: Sınav başlatıldığında expires_at hesaplanır. Süre dolduğunda cevap kabul edilmez ve sınav otomatik sonlandırılır.

GET /exams/app/current Auth Güncel Sınavlar

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

Test Et

GET /exams/app/upcoming Auth Yaklaşan Sınavlar

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

Test Et

GET /exams/app/past Auth Geçmiş Sınavlar

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

Test Et

POST /exams/app/{assignment_id}/start Auth Sınav Başlat

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

Test Et

GET /exams/app/sessions/{session_id} Auth Sınav Oturumu

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

Test Et

POST /exams/app/sessions/{session_id}/answer Auth Cevap Kaydet

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

Request Body

Parametre	Tip	Açıklama
question_id Zorunlu	integer	Soru ID'si
answer_json Zorunlu	mixed	Cevap (şık, metin vb.)

Test Et

POST /exams/app/sessions/{session_id}/submit Auth Sınavı Bitir

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

Test Et

GET /exams/app/sessions/{session_id}/result Auth Sınav Sonucu

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

Test Et

Takvim & Etkinlik

5 Endpoint

Sınav, ders, etkinlik ve tatil tarihlerini yönetir. Aylık/günlük görünüm ve yaklaşan etkinlikler.

GET /calendar/app/month Auth Aylık Görünüm

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

Query Parametreleri

Parametre	Tip	Açıklama
year Zorunlu	integer	Yıl (örn: 2025)
month Zorunlu	integer	Ay (1-12)

Test Et

GET /calendar/app/day Auth Günlük Görünüm

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

Query Parametreleri

Parametre	Tip	Açıklama
date Zorunlu	string	Tarih (YYYY-MM-DD)

Test Et

GET /calendar/app/today Auth Bugün

Bugünkü etkinlikleri döner.

Test Et

GET /calendar/app/upcoming Auth Yaklaşan Etkinlikler

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

Query Parametreleri

Parametre	Tip	Açıklama
days Opsiyonel	integer	Gün sayısı (varsayılan: 7)

Test Et

GET /calendar/app/events/{id} Auth Etkinlik Detayı

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

Test Et

Bildirimler & Duyurular

8 Endpoint

Sistem bildirimleri, duyurular ve bildirim ayarları. Push bildirimine hazır yapı.

GET /notifications/app Auth Bildirim Listesi

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

Test Et

GET /notifications/app/unread-count Auth Okunmamış Sayısı

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

Test Et

POST /notifications/app/{id}/read Auth Okundu İşaretle

Belirli bir bildirimi okundu olarak işaretler.

Test Et

POST /notifications/app/read-all Auth Tümünü Okundu İşaretle

Tüm bildirimleri okundu olarak işaretler.

Test Et

GET /notifications/app/feed Auth Birleşik Feed

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

Test Et

GET /notifications/settings Auth Bildirim Ayarları

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

Test Et

POST /notifications/settings Auth Ayarları Güncelle

Bildirim tercihlerini günceller.

Request Body

Parametre	Tip	Açıklama
push_enabled Opsiyonel	boolean	Push bildirimleri
email_enabled Opsiyonel	boolean	E-posta bildirimleri
exam_reminders Opsiyonel	boolean	Sınav hatırlatıcıları

Test Et

İlerleme & Rozet & XP

7 Endpoint

Kullanıcının tüm gelişimini takip eden sistem. XP → Level → Rozet zinciri ve modül bazlı ilerleme.

GET /progress/overview Auth Genel Bakış

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

Test Et

GET /progress/modules Auth Modül Bazlı İlerleme

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

Test Et

GET /progress/badges Auth Rozetlerim

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

Test Et

GET /progress/xp-history Auth XP Geçmişi

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

Test Et

GET /progress/leaderboard Auth Sıralama

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

Test Et

POST /progress/daily-check Auth Günlük Kontrol

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

Test Et

POST /progress/badges/{id}/showcase Auth Rozet Vitrin

Rozeti profilinde göster/gizle.

Test Et

Profil & Hesap

10 Endpoint

Kullanıcı profili, avatar, şifre değişikliği ve hesap güvenliği işlemleri.

GET /profile Auth Profil Bilgisi

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

Test Et

PUT /profile Auth Profil Güncelle

Profil bilgilerini günceller.

Request Body

Parametre	Tip	Açıklama
name Opsiyonel	string	Ad soyad
grade Opsiyonel	integer	Sınıf (1-12)
school_name Opsiyonel	string	Okul adı
city Opsiyonel	string	Şehir
birth_date Opsiyonel	date	Doğum tarihi (YYYY-MM-DD)

Test Et

Name

Grade

School

City

GET /profile/education-info Auth Eğitim Bilgilerini Getir

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.

Test Et

POST /profile/education-info Auth Eğitim Bilgilerini Kaydet

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

Request Body

Parametre	Tip	Açıklama
education_level Zorunlu	string	Eğitim seviyesi (primary, secondary, high_school, university, graduate, other)
grade Opsiyonel	integer	Sınıf (1-12 arası, sadece ilkokul/ortaokul/lise için)
school_name Opsiyonel	string	Okul adı (max 255 karakter)

Test Et

Education Level

Grade

School Name

POST /profile/avatar Auth Avatar Yükle

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

Bu endpoint dosya yüklemesi gerektirir. Postman veya mobil uygulama ile test edin.

POST /profile/change-password Auth Şifre Değiştir

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

Request Body

Parametre	Tip	Açıklama
current_password Zorunlu	string	Mevcut şifre
password Zorunlu	string	Yeni şifre (min: 8)
password_confirmation Zorunlu	string	Yeni şifre tekrarı

Test Et

POST /profile/change-email Auth Email Değiştir

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

Request Body

Parametre	Tip	Açıklama
email Zorunlu	string	Yeni email adresi
password Zorunlu	string	Mevcut şifre (doğrulama için)

Test Et

GET /profile/security-logs Auth Güvenlik Logları

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

Test Et

DELETE /profile Auth Hesap Sil

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

Dikkat: Bu işlem geri alınamaz! Hesap ve tüm veriler kalıcı olarak silinir.

Request Body

Parametre	Tip	Açıklama
password Zorunlu	string	Mevcut şifre (doğrulama için)

Test Et

İnteraktif Konuşma (Practice)

7 Endpoint

AI destekli interaktif konuşma pratiği. Akış: GET /practice/scenarios ile kullanıcının sınıfı ve seviyesine göre senaryolar çekilir; listeden bir senaryonun scenario_id değeri ile POST /practice/start çağrılarak konuşma başlatılır. Senaryolar panelden (Pratik Senaryoları) sınıf/ünite/zorluk seviyeli oluşturulur.

Panel Senaryo Alanları → API Parametre Eşlemesi

Panelden oluşturulan senaryoda yer alan alanlar, konuşma başlatılırken aşağıdaki API parametrelerine map edilir.

Panel alanı	API parametresi	Açıklama
Konu Başlığı (Topic)	`topic` + `llm_role`	Ana konu başlığı hem `topic` hem `llm_role` parametrelerine aynı anda eklenir (llm_role: "Konu Başlığı – rol metni" formatında)
Konu İçerik Detayı (Senaryo / Metin Bağlamı)	`details`	Senaryo veya metin bağlamı
Hedeflenen Özel Kelimeler (Vocabulary)	`vocabulary`	Pratik yapılacak kelime listesi (array)
Hedeflenen Gramer Kuralları (Grammar / Tense)	`target_grammar`	Hedef gramer kuralları veya tense
Zorluk Seviyesi (Level)	`difficulty`	beginner / intermediate / advanced veya A1–C2

GET /practice/voices Public Sesler Listesi

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

Test Et

GET /practice/scenarios Auth Senaryo Listesi (Kullanıcı Sınıfı / Seviye)

Giriş yapan kullanıcının sınıfı ve İngilizce seviyesine göre konuşma senaryolarını döner. Kullanıcının kayıtlı olduğu sınıf (grade_level_id) ve o sınıftaki dil seviyesi (level_band_id) varsayılan olarak kullanılır; query parametreleri ile override edilebilir.

Query Parameters (Opsiyonel)

Parametre verilmezse kullanıcının sınıfı ve seviyesi kullanılır. Verilirse bu değerler override edilir.

Parametre	Tip	Açıklama
grade_level_id Opsiyonel	integer	Sınıf ID. Yoksa kullanıcının kayıtlı olduğu sınıftan alınır.
level_band_id Opsiyonel	integer	Seviye bandı ID (A1, A2, B1 vb.). Yoksa kullanıcının o sınıftaki dil seviyesinden alınır.
unit_id Opsiyonel	integer	Ünite ID ile filtre (panel senaryoları)
difficulty Opsiyonel	string	Varsayılan senaryolarda filtre: `beginner`, `intermediate`, `advanced`
category Opsiyonel	string	Varsayılan senaryolarda filtre: travel, business, daily_life, vb.

Test Et

Difficulty (Opsiyonel)

Category (Opsiyonel)

POST /practice/start Auth Konuşma Başlat

Yeni bir konuşma oturumu başlatır. Senaryo ID ile başlatma: scenario_id göndererek panelden seçilen senaryoyla konuşmayı başlatın; topic, details, vocabulary, target_grammar, difficulty ve diğer alanlar otomatik doldurulur. TTS destekli AI partner ile konuşma pratiği yapılır; başlangıç mesajı ve ses (base64) ile birlikte session_id döner.

Senaryo ID ile Konuşma Başlatma (Önerilen)

Parametre	Tip	Açıklama
scenario_id Opsiyonel	integer	GET /practice/scenarios ile dönen listeden seçilen senaryonun `id` veya `scenario_id` değeri. Verildiğinde topic, details, vocabulary, target_grammar, difficulty, partner_name, llm_role, total_steps senaryodan alınır; ek parametre göndermeniz gerekmez.

Request Body - Zorunlu Parametreler (scenario_id yoksa)

Parametre	Tip	Açıklama
partner_name Zorunlu*	string	AI partnerin adı (örn: "Sarah", "Emma"). *scenario_id verilirse opsiyonel
llm_role Zorunlu*	string	AI'ın rol açıklaması. Konu Başlığı (topic) ile birlikte gönderilir (topic – llm_role). *scenario_id verilirse opsiyonel
total_steps Zorunlu*	integer	Konuşma tur sayısı (3-30). *scenario_id verilirse opsiyonel

Request Body - Opsiyonel Parametreler

Parametre	Tip	Açıklama
topic Opsiyonel	string	Konu Başlığı. Aynı değer `llm_role` ile birlikte de kullanılır (topic – llm_role). Panel: Konu Başlığı
details Opsiyonel	string	Senaryo / metin bağlamı. Panel: Konu İçerik Detayı
vocabulary Opsiyonel	array	Hedeflenen özel kelimeler. Panel: Hedeflenen Özel Kelimeler
target_grammar Opsiyonel	string	Hedeflenen gramer kuralları / tense. Panel: Hedeflenen Gramer Kuralları
difficulty Opsiyonel	string	Zorluk seviyesi. Panel: Zorluk Seviyesi. `beginner`, `intermediate`, `advanced` veya A1–C2 (varsayılan: intermediate)
voice_gender Opsiyonel	string	`male` veya `female` (varsayılan: female)
voice_id Opsiyonel	string	Spesifik ses ID'si (female_1-female_8, male_1-male_8)
speech_rate Opsiyonel	number	Konuşma hızı (0.5-1.5, varsayılan: 1.0) - 0.75=yavaş, 1.0=normal, 1.25=hızlı
enable_tts Opsiyonel	boolean	Ses çıktısı aktif olsun mu? (varsayılan: true)
scenario Opsiyonel	string	Backward compatibility: Senaryo adı (restaurant, hotel vb.) - partner_name ve llm_role için varsayılan değerler sağlar
ai_role Opsiyonel	string	Backward compatibility: llm_role için alias
include_audio Opsiyonel	boolean	Backward compatibility: enable_tts için alias

Test Et

Scenario ID (Panel senaryosu) Doluysa topic, details, vocabulary, target_grammar, difficulty otomatik dolar

Partner Name *

LLM Role *

Total Steps *

Difficulty (Opsiyonel)

Topic (Konu Başlığı) (Opsiyonel) Hem topic hem llm_role'e eklenir

Voice Gender (Opsiyonel)

Voice ID (Opsiyonel)

Speech Rate (Opsiyonel)

Details (Konu İçerik Detayı)

Target Grammar (Hedef Gramer)

Vocabulary (Opsiyonel) JSON array formatında (virgülle ayırın)

Enable TTS (Ses çıktısı)

POST /practice/respond Auth Mesaj Gönder

Konuşmada mesaj gönderir ve AI yanıtını alır. Opsiyonel olarak ses dosyası ve düzeltme de döner.

Request Body

Parametre	Tip	Açıklama
session_id Zorunlu	string	Konuşma oturum ID'si (start endpoint'inden dönen session_id)
user_message Zorunlu	string	Kullanıcının mesajı
conversation_id Opsiyonel	string	Backward compatibility: session_id için alias
message Opsiyonel	string	Backward compatibility: user_message için alias
include_audio Opsiyonel	boolean	AI yanıtının sesli olup olmayacağı
include_correction Opsiyonel	boolean	Gramer/yazım düzeltmesi verilsin mi?

Test Et

POST /practice/end Auth Konuşmayı Bitir

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

Request Body

Parametre	Tip	Açıklama
session_id Zorunlu	string	Konuşma oturum ID'si (start endpoint'inden dönen session_id)
conversation_id Opsiyonel	string	Backward compatibility: session_id için alias

Test Et

GET /practice/conversations Auth Geçmiş Konuşmalar

Kullanıcının geçmiş konuşmalarını listeler. Senaryo, zorluk seviyesi ve durum (aktif/tamamlanmış) ile filtreleme yapılabilir.

Query Parameters (Opsiyonel)

Parametre	Tip	Açıklama
scenario Opsiyonel	string	Senaryo filtresi (restaurant, hotel, airport vb.)
difficulty Opsiyonel	string	`beginner`, `intermediate`, `advanced`
status Opsiyonel	string	`active` (devam eden) veya `completed` (tamamlanmış)
per_page Opsiyonel	integer	Sayfa başına kayıt sayısı (varsayılan: 20, maksimum: 50)

Test Et

Scenario (Opsiyonel)

Status (Opsiyonel)

GET /practice/conversations/{id} Auth Konuşma Detayı

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

URL Parameters

Parametre	Tip	Açıklama
id Zorunlu	integer	Konuşma ID'si

Test Et

API Durumu (External)

2 Endpoint

Harici API servislerinin durumunu ve bilgilerini kontrol etmek için kullanılan endpoint'ler. Sistemin sağlık durumu ve versiyon bilgisi alınabilir.

GET /external/info Public API Bilgisi

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

Test Et

GET /external/health Public Sağlık Kontrolü

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

Test Et

Admin API

12 Endpoint

Admin yetkisi gerektiren endpoint'ler. Onboarding flow, step ve option yönetimi.

Yetki Gerekli: Bu endpoint'ler sadece admin rolüne sahip kullanıcılar tarafından erişilebilir. Base URL: /api/admin/onboarding

GET /api/admin/onboarding/flows Admin Onboarding Flow Listesi

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

Test Et

POST /api/admin/onboarding/flows Admin Flow Oluştur

Yeni onboarding flow'u oluşturur.

Request Body

Parametre	Tip	Açıklama
name Zorunlu	string	Flow adı
description Opsiyonel	string	Açıklama
is_active Opsiyonel	boolean	Aktif mi? (varsayılan: false)

Test Et

GET /api/admin/onboarding/flows/{flow} Admin Flow Detayı

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

Test Et

POST /api/admin/onboarding/flows/{flow}/activate Admin Flow Aktifleştir

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

Test Et

GET /api/admin/onboarding/flows/{flow}/steps Admin Step Listesi

Flow'a ait adımları listeler.

Test Et

GET /api/admin/onboarding/steps/{step}/options Admin Option Listesi

Step'e ait seçenekleri listeler.