> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Versiyonlama

> Flextell API'nin sürüm politikası, kırıcı değişiklik tanımı ve geçiş süreci.

Flextell API'nin sürüm stratejisi **URL-segmentli** versiyonlamadır. Şu anda aktif olan tek sürüm `v1`'dir ve tüm uçlar `https://<env>.flextell.ai/api/v1/...` altında yaşar.

## Sürüm stratejisi

| Sürüm | Durum | Yol         | Notlar                           |
| ----- | ----- | ----------- | -------------------------------- |
| `v1`  | Aktif | `/api/v1/*` | Tüm üretim trafiği               |
| `v2`  | Yok   | —           | İleride eklenirse duyuru yapılır |

Yeni bir ana sürüm (örn. `v2`) eklendiğinde:

1. `v1` en az **12 ay** boyunca paralel çalışmaya devam eder.
2. Yeni üretilen uygulamalar `v2`'ye yönlendirilir; `v1` token'ları otomatik olarak `v2`'ye yükseltilmez — uygulamanızın kod tarafında taşıma yapmanız gerekir.
3. `v1`'in kaldırılma tarihi en az **6 ay önce** [Changelog](/resources/changelog) üzerinden duyurulur.

## Neyi kırıcı (breaking) saymıyoruz?

Aşağıdaki değişiklikler **geriye uyumlu** kabul edilir ve `v1` içinde minor versiyon çıkarmadan yayınlanır:

* Bir JSON yanıtına **yeni bir alan** eklemek.
* Yeni bir **opsiyonel** istek parametresi eklemek (varsayılanı mevcut davranışla uyumlu).
* Yeni bir **endpoint** eklemek.
* Yeni bir **event payload alanı** eklemek.
* Yeni bir **scope** eklemek (mevcut scope'ların yetkisi aynı kalır).
* Daha fazla HTTP status code kombinasyonu eklemek (zaten belgelenmiş olanları kaldırmadan).
* Hata mesaj metinlerini düzeltmek (hata kodu aynı kaldığı sürece).

<Note>
  İstemcilerinizde **bilinmeyen JSON alanlarını göz ardı eden** bir parsing yaklaşımı kullanın. Aksi hâlde bu geriye uyumlu eklemeler bile entegrasyonunuzu bozabilir.
</Note>

## Neyi kırıcı sayıyoruz?

Şunlar **kırıcı değişiklik** kabul edilir ve yalnızca yeni bir ana sürümde (ör. `v2`) yayınlanır:

* Bir uç'un **URL'ini** değiştirmek.
* Bir yanıt alanını **kaldırmak** veya **tipini** değiştirmek (string → object gibi).
* Zorunlu olmayan bir parametreyi zorunlu hale getirmek.
* Bir enum değerini kaldırmak.
* Bir scope'un **yetkisini daraltmak** (genişletmek kırıcı değildir).
* HTTP status kodlarının varsayılan kombinasyonunu değiştirmek (örn. 200 yerine 204'e geçmek).

## İstisnalar ve önceden bildirimsiz değişiklikler

Güvenlik veya uyumluluk gereğince **acil** yapılması gereken değişiklikleri önceden bildirmeden uygulayabiliriz. Örneğin:

* Kritik bir güvenlik açığı için bir alanın redaction'ı.
* KVKK/HIPAA uyumu için bir yanıtın maskelenmesi veya kaldırılması.

Bu tip değişiklikler mümkün olduğunca dar kapsamda tutulur ve Changelog'a **yapıldıktan sonra** not düşülür.

## Dokümantasyon tutarlılığı

Bu dokümantasyon, canlı API kodundan **otomatik** üretilen OpenAPI şeması ile senkronize tutulur. Yazılı rehberler (bu sayfa gibi) ve OpenAPI referansı arasında bir tutarsızlık görürseniz:

* OpenAPI şeması "doğru" kabul edilir (kod ile birebir eşleştirilir).
* Yazılı rehber açıklayıcı bir özet sunar; ciddi fark varsa [destek](/resources/support) ile iletişime geçin.

## Hangi sürümü kullanıyorum?

Token aldığınızda sürüm bilgisi token'da taşınmaz — **URL** ile belirlenir. Talep attığınız URL hangi sürümü hedefliyorsa ona göre yanıt alırsınız.

```bash theme={null}
# Şu an kullanılan tek sürüm
GET https://dev.flextell.ai/api/v1/account
```

## OpenAPI şemasını indirme

```
GET https://dev.flextell.ai/docs/api.json
```

Bu URL her zaman **v1**'in güncel şemasıdır. CI'ınızda tip üretimi için bu şemayı çekebilirsiniz.

## Duyuru kanalları

Önemli değişiklikler ve API ile ilgili bakım duyuruları:

* [Changelog](/resources/changelog) — kalıcı kayıt.
* E-posta — kullanıcı uygulamanızın iletişim adresine önemli değişiklikler için gönderilir.
* [Destek](/resources/support) — sorularınız için birebir iletişim.