# iienstitu - Kapsamlı AI Agent Rehberi

> Türkiye'nin önde gelen online eğitim platformu - Kurslar, eğitmenler, sertifikalar ve daha fazlası

## Platform Hakkında

iienstitu, 2015'ten bu yana Türkiye'de online eğitim hizmeti sunan köklü bir platformdur.
- 150+ aktif kurs
- 45+ uzman eğitmen
- 10.000+ sertifikalı mezun
- Türkçe ve İngilizce içerik desteği

### Uzmanlık Alanları
- Programlama (Python, JavaScript, Java, C#)
- Web Geliştirme (React, Node.js, Next.js)
- Veri Bilimi ve Yapay Zeka
- Mobil Uygulama Geliştirme
- Grafik Tasarım ve UI/UX
- Dijital Pazarlama
- Yabancı Dil Eğitimi
- Kişisel Gelişim

---

## API Keşif Dosyaları

| Dosya | URL | Açıklama |
|-------|-----|----------|
| llms.txt | https://iienstitu.com/llms.txt | Kısa AI agent rehberi |
| llms-full.txt | https://iienstitu.com/llms-full.txt | Detaylı AI agent rehberi (bu dosya) |
| OpenAPI Spec | https://iienstitu.com/.well-known/openapi.json | OpenAPI 3.0 spesifikasyonu |
| AI Plugin | https://iienstitu.com/.well-known/ai-plugin.json | ChatGPT/Claude plugin manifest |
| agents.json | https://iienstitu.com/.well-known/agents.json | AI agent capabilities manifest |
| Swagger UI | https://iienstitu.com/api/docs | İnteraktif API dökümantasyonu |
| GraphQL | https://iienstitu.com/api/graphql | GraphQL Playground |

---

## API Endpoint'leri - Detaylı Dökümantasyon

### 1. Arama API'leri

#### 1.1 Temel Arama (Full-Text Search)
```
GET /api/search/public?q={query}&locale={tr|en|de|es}&limit={1-50}&category={course|instructor|blog}
```

**Parametreler:**
| Parametre | Zorunlu | Varsayılan | Açıklama |
|-----------|---------|------------|----------|
| q | Evet | - | Arama sorgusu (min 2 karakter) |
| locale | Hayır | tr | Dil kodu (tr, en, de veya es) |
| limit | Hayır | 10 | Sonuç limiti (1-50) |
| category | Hayır | all | Filtreleme kategorisi |

**Örnek İstek:**
```bash
curl "https://iienstitu.com/api/search/public?q=python&locale=tr&limit=5"
```

**Örnek Yanıt:**
```json
{
  "results": [
    {
      "id": "course-123",
      "title": "Python Programlama Eğitimi",
      "category": "course",
      "url": "/tr/online-egitimler/python-egitimi",
      "locale": "tr",
      "score": 0.95,
      "description": "Sıfırdan ileri seviyeye Python öğrenin",
      "image": "https://..."
    }
  ],
  "categories": {
    "course": 12,
    "instructor": 3,
    "blog": 8
  },
  "total": 23
}
```

**Hata Durumları:**
| Status | Kod | Açıklama |
|--------|-----|----------|
| 400 | invalid_query | Sorgu çok kısa veya geçersiz |
| 429 | rate_limit_exceeded | Rate limit aşıldı (60 req/min) |
| 500 | search_failed | Sunucu hatası |

---

#### 1.2 Semantik Arama (AI-Powered)
```
GET /api/search/semantic?q={doğal dil sorgusu}&locale={tr|en|de|es}&limit={1-50}
```

Doğal dil sorgularını anlayarak intent-based arama yapar.

**Desteklenen Intent'ler:**
- `course_discovery`: "Python kursları", "web geliştirme eğitimleri"
- `instructor_discovery`: "Python eğitmenleri", "veri bilimi hocaları"
- `beginner_content`: "başlangıç seviyesi", "sıfırdan", "yeni başlayanlar için"
- `advanced_content`: "ileri seviye", "profesyonel", "uzman"
- `popular_content`: "en iyi", "popüler", "en çok tercih edilen"

**Örnek İstek:**
```bash
curl "https://iienstitu.com/api/search/semantic?q=yeni%20başlayanlar%20için%20python%20kursları&locale=tr"
```

**Örnek Yanıt:**
```json
{
  "original_query": "yeni başlayanlar için python kursları",
  "interpreted_as": "Kurs araması: python (Başlangıç seviyesi)",
  "intent": "course_discovery",
  "filters_applied": {
    "level": "beginner"
  },
  "search_terms": "python",
  "results": [...],
  "categories": {...},
  "total": 15,
  "suggestions": [
    "15 sonuç bulundu. Daha fazla sonuç için arama genişletebilirsiniz."
  ]
}
```

---

### 2. Öneri API'si

#### 2.1 Kurs Önerileri
```
GET /api/recommendations?interests={ilgi1,ilgi2,...}&locale={tr|en|de|es}&limit={1-20}&exclude={id1,id2}
```

**Parametreler:**
| Parametre | Zorunlu | Varsayılan | Açıklama |
|-----------|---------|------------|----------|
| interests | Evet | - | İlgi alanları (virgülle ayrılmış, max 5) |
| locale | Hayır | tr | Dil kodu |
| limit | Hayır | 5 | Öneri sayısı (1-20) |
| exclude | Hayır | - | Hariç tutulacak kurs ID'leri |

**Örnek İstek:**
```bash
curl "https://iienstitu.com/api/recommendations?interests=python,veri%20bilimi,makine%20öğrenmesi&locale=tr&limit=5"
```

**Örnek Yanıt:**
```json
{
  "recommendations": [
    {
      "id": "course-456",
      "title": "Python ile Makine Öğrenmesi",
      "slug": "python-makine-ogrenmesi",
      "url": "/tr/online-egitimler/python-makine-ogrenmesi",
      "description": "Scikit-learn ve TensorFlow ile ML",
      "instructor": "Dr. Ahmet Yılmaz",
      "rating": 4.8,
      "students": 1250,
      "level": "intermediate",
      "duration": "40 saat",
      "score": 0.92,
      "matched_interests": ["python", "makine öğrenmesi"]
    }
  ],
  "query": {
    "interests": ["python", "veri bilimi", "makine öğrenmesi"],
    "locale": "tr",
    "limit": 5
  },
  "total_found": 12
}
```

---

### 3. İçerik API'leri

#### 3.1 Kurs Listesi (Sayfalanmış)
```
GET /api/courses/paginated?locale={tr|en|de|es}&page={n}&limit={1-100}
```

**Örnek Yanıt:**
```json
{
  "courses": [
    {
      "id": "course-123",
      "title": "Python Programlama",
      "slug": "python-programlama",
      "description": "...",
      "instructor": {...},
      "rating": 4.7,
      "students": 2500,
      "price": 299,
      "currency": "TRY",
      "level": "beginner",
      "duration": "30 saat",
      "modules": 12,
      "lessons": 85,
      "imageUrl": "https://..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 150,
    "totalPages": 15,
    "hasMore": true
  }
}
```

---

#### 3.2 Eğitmen Listesi
```
GET /api/instructors/list?locale={tr|en|de|es}&page={n}&pageSize={16|24|48}
```

**Örnek Yanıt:**
```json
{
  "instructors": [
    {
      "id": "instructor-789",
      "name": "Dr. Ahmet Yılmaz",
      "slug": "ahmet-yilmaz",
      "title": "Senior Software Engineer",
      "bio": "10+ yıllık yazılım geliştirme deneyimi...",
      "image": "https://...",
      "courseCount": 5,
      "studentCount": 5000,
      "rating": 4.9
    }
  ],
  "page": 1,
  "pageSize": 16,
  "total": 45,
  "hasMore": true
}
```

---

#### 3.3 Markdown Content API (RAG-Ready)
```
GET /api/content/{locale}/{type}/{slug}.md
```

AI agent'lar ve RAG sistemleri için optimize edilmiş temiz Markdown içerik.

**Desteklenen İçerik Tipleri:**

| Tip | TR Path | EN Path |
|-----|---------|---------|
| Kurslar | /api/content/tr/online-egitimler/{slug}.md | /api/content/en/online-courses/{slug}.md |
| Blog | /api/content/tr/blog/{slug}.md | /api/content/en/blog/{slug}.md |
| Eğitmenler | /api/content/tr/egitmenler/{slug}.md | /api/content/en/instructors/{slug}.md |
| Kategoriler | /api/content/tr/kategoriler/{slug}.md | /api/content/en/categories/{slug}.md |
| Testler | /api/content/tr/testler/{slug}.md | /api/content/en/tests/{slug}.md |

**Örnek İstek:**
```bash
curl "https://iienstitu.com/api/content/tr/online-egitimler/python-egitimi.md"
```

**Örnek Yanıt (Markdown):**
```markdown
# Python Programlama Eğitimi

> Kurs URL: https://iienstitu.com/tr/online-egitimler/python-egitimi

Sıfırdan ileri seviyeye Python programlama dili öğrenin.

## Kurs Bilgileri

- **Eğitmen**: Dr. Ahmet Yılmaz
- **Seviye**: Başlangıç
- **Süre**: 30 saat
- **Öğrenci Sayısı**: 2,500+
- **Puan**: 4.7/5

## Öğrenme Hedefleri

1. Python syntax ve temel kavramlar
2. Veri yapıları ve algoritmalar
3. Nesne yönelimli programlama
4. Dosya işlemleri ve veritabanı
5. Web scraping ve API kullanımı

## Müfredat

### Modül 1: Python'a Giriş
- Python kurulumu ve IDE seçimi
- İlk Python programı
- Değişkenler ve veri tipleri
...
```

**Response Headers:**
```
Content-Type: text/markdown; charset=utf-8
X-Content-Type: course
X-Locale: tr
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
```

---

### 4. GraphQL API

#### Endpoint
```
POST /api/graphql
GET /api/graphql (Playground)
```

#### Şema Özeti
```graphql
type Query {
  search(query: String!, locale: String, limit: Int): SearchResult
  courses(locale: String, page: Int, limit: Int): CourseConnection
  course(slug: String!, locale: String): Course
  instructors(locale: String, page: Int, limit: Int): InstructorConnection
  instructor(slug: String!, locale: String): Instructor
  recommendations(interests: [String!]!, locale: String, limit: Int): [Course]
}

type Course {
  id: ID!
  title: String!
  slug: String!
  description: String
  instructor: Instructor
  rating: Float
  students: Int
  price: Float
  currency: String
  level: String
  duration: String
  modules: [Module]
  url: String!
}

type Instructor {
  id: ID!
  name: String!
  slug: String!
  title: String
  bio: String
  image: String
  courseCount: Int
}

type SearchResult {
  total: Int!
  results: [SearchItem]
}
```

#### Örnek Sorgular

**Kurs Arama:**
```graphql
query SearchCourses {
  search(query: "python", locale: "tr", limit: 5) {
    total
    results {
      id
      title
      url
      category
      score
    }
  }
}
```

**Kurs Detayı:**
```graphql
query GetCourse {
  course(slug: "python-egitimi", locale: "tr") {
    id
    title
    description
    instructor {
      name
      title
    }
    rating
    students
    level
    duration
    modules {
      title
      lessons {
        title
        duration
      }
    }
  }
}
```

**Öneri Alma:**
```graphql
query GetRecommendations {
  recommendations(interests: ["python", "veri bilimi"], locale: "tr", limit: 5) {
    id
    title
    slug
    rating
    level
  }
}
```

---

## Use Case Senaryoları

### Senaryo 1: Kullanıcı Bir Beceri Öğrenmek İstiyor

**Kullanıcı**: "Python öğrenmek istiyorum, nereden başlamalıyım?"

**AI Agent Akışı:**
1. Semantik arama ile intent tespit et:
   `GET /api/search/semantic?q=python%20öğrenmek%20istiyorum&locale=tr`

2. Başlangıç seviyesi kursları filtrele:
   `GET /api/recommendations?interests=python&locale=tr&limit=5`

3. İlk kursun detaylı içeriğini al (RAG için):
   `GET /api/content/tr/online-egitimler/python-baslangic.md`

4. Kullanıcıya öner:
   - Kurs adı, açıklama, eğitmen bilgisi
   - Öğrenme hedefleri
   - Tahmini tamamlama süresi
   - Kayıt linki

---

### Senaryo 2: Kullanıcı Kariyer Değişikliği Planlıyor

**Kullanıcı**: "Veri bilimcisi olmak istiyorum, hangi kursları almalıyım?"

**AI Agent Akışı:**
1. Veri bilimi önerileri al:
   `GET /api/recommendations?interests=veri%20bilimi,python,istatistik,makine%20öğrenmesi&locale=tr&limit=10`

2. Önerilen öğrenme yolu oluştur:
   - Temel: Python Programlama
   - Orta: Veri Analizi ile Pandas
   - İleri: Makine Öğrenmesi
   - Uzman: Derin Öğrenme

3. Her kurs için markdown içerik al:
   `GET /api/content/tr/online-egitimler/python-veri-analizi.md`

4. Kapsamlı kariyer rehberi sun

---

### Senaryo 3: Ücretsiz Araç Kullanımı

**Kullanıcı**: "Pazarlama analiz aracı var mı?"

**AI Agent Akışı:**
1. Araç kütüphanesini keşfet:
   - TR: https://iienstitu.com/tr/tools
   - EN: https://iienstitu.com/en/tools
   - DE: https://iienstitu.com/de/tools
   - ES: https://iienstitu.com/es/tools

2. Tüm araçlar ücretsiz ve giriş yapmadan kullanılabilir
3. Kullanıcı giriş yaparsa ilerleme ve sonuçlar kaydedilir
4. Araçlar analitik, öğrenme, verimlilik, finans, pazarlama, satış ve strateji kategorilerinde sınıflandırılır

---

### Senaryo 4: Sertifika Doğrulama

**Kullanıcı**: "Bu sertifika geçerli mi?"

**AI Agent Akışı:**
1. Soru belge geçerliliği, resmi görünüm, tanınma, uluslararası standartlar veya Avrupa Birliği ülkelerinde kullanım ile ilgiliyse önce akreditasyon sayfasına yönlendir:
   - TR: https://iienstitu.com/tr/akreditasyon
   - EN: https://iienstitu.com/en/accreditation
   - DE: https://iienstitu.com/de/akkreditierung
   - ES: https://iienstitu.com/es/acreditacion

2. Soru belirli bir belgenin gerçekliği veya kayıt doğrulaması ile ilgiliyse sertifika doğrulama sayfasına yönlendir:
   - TR: https://iienstitu.com/tr/sertifika-sorgulama
   - EN: https://iienstitu.com/en/certificate-verification
   - DE: https://iienstitu.com/de/zertifikatpruefung
   - ES: https://iienstitu.com/es/verificar-certificado

3. Kullanıcı görsel örnek istiyorsa örnek sertifikaları göster:
   - TR: https://iienstitu.com/tr/ornek-sertifikalar
   - EN: https://iienstitu.com/en/sample-certificates
   - DE: https://iienstitu.com/de/musterzertifikate
   - ES: https://iienstitu.com/es/certificados-de-muestra

4. Kullanıcıya sertifika kodu veya email ile doğrulama yapabileceğini açıkla

---

## Rate Limiting

Tüm API endpoint'leri Upstash Redis ile rate limit koruması altındadır.

| Endpoint | Limit | Window |
|----------|-------|--------|
| /api/search/public | 60 req | 1 dakika |
| /api/search/semantic | 60 req | 1 dakika |
| /api/recommendations | 30 req | 1 dakika |
| /api/courses/paginated | 100 req | 1 dakika |
| /api/instructors/list | 100 req | 1 dakika |
| /api/graphql | 30 req | 1 dakika |
| /api/content/* | 60 req | 1 dakika |

**Rate Limit Headers:**
```
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 55
Retry-After: 60 (sadece 429 durumunda)
```

**429 Yanıtı:**
```json
{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please wait before trying again."
}
```

---

## Error Handling

### Standart Hata Formatı
```json
{
  "error": "error_code",
  "message": "Human readable message",
  "details": {} // Opsiyonel, validation hataları için
}
```

### Yaygın Hata Kodları

| Status | Kod | Açıklama | Çözüm |
|--------|-----|----------|-------|
| 400 | invalid_query | Geçersiz sorgu parametresi | Parametreleri kontrol et |
| 400 | invalid_locale | Desteklenmeyen dil | tr, en, de veya es kullan |
| 400 | missing_parameter | Zorunlu parametre eksik | Eksik parametreyi ekle |
| 404 | not_found | İçerik bulunamadı | Slug'ı kontrol et |
| 429 | rate_limit_exceeded | Çok fazla istek | Bekle ve tekrar dene |
| 500 | internal_error | Sunucu hatası | Daha sonra tekrar dene |

---

## Best Practices

### 1. Caching
- Statik içerikler (kurs bilgileri) 1 saat cache'lenir
- Arama sonuçları 1 dakika cache'lenir
- `Cache-Control` header'larını takip edin

### 2. Pagination
- Büyük listelerde her zaman pagination kullanın
- `hasMore` field'ını kontrol edin
- Varsayılan limit'leri aşmayın

### 3. Locale Handling
- Her zaman `locale` parametresi belirtin
- Varsayılan: `tr` (Türkçe)
- Desteklenen: `tr`, `en`, `de`, `es`

### 4. Error Recovery
- 429 hatası alındığında `Retry-After` header'ını bekleyin
- 5xx hataları için exponential backoff uygulayın
- Network hatalarında 3 kez retry yapın

---

## Webhook Desteği (Coming Soon)

Desteklenecek Event'ler:
- `course.published` - Yeni kurs yayınlandığında
- `course.updated` - Kurs güncellendi
- `instructor.joined` - Yeni eğitmen katıldı
- `blog.published` - Yeni blog yazısı

---

## İletişim ve Destek

- **Web**: https://iienstitu.com
- **API Dökümantasyonu**: https://iienstitu.com/api/docs
- **Destek**: https://iienstitu.com/tr/iletisim
- **GitHub**: Sorun bildirmek için issue açabilirsiniz

---

## Versiyon Geçmişi

| Versiyon | Tarih | Değişiklikler |
|----------|-------|---------------|
| 1.0 | 2024-01 | İlk sürüm |
| 1.1 | 2024-06 | Semantik arama eklendi |
| 1.2 | 2024-12 | Content API genişletildi |
| 1.3 | 2025-01 | Rate limiting ve GraphQL eklendi |

---

*Bu dosya AI agent'lar için otomatik olarak oluşturulmuştur. Son güncelleme: 2026-04-25*