# API Reference (Türkçe)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/API_REFERENCE.md) · 🇪🇹 [am](../../../am/docs/reference/API_REFERENCE.md) · 🇸🇦 [ar](../../../ar/docs/reference/API_REFERENCE.md) · 🇦🇿 [az](../../../az/docs/reference/API_REFERENCE.md) · 🇧🇬 [bg](../../../bg/docs/reference/API_REFERENCE.md) · 🇧🇩 [bn](../../../bn/docs/reference/API_REFERENCE.md) · 🇧🇦 [bs](../../../bs/docs/reference/API_REFERENCE.md) · 🇨🇿 [cs](../../../cs/docs/reference/API_REFERENCE.md) · 🇩🇰 [da](../../../da/docs/reference/API_REFERENCE.md) · 🇩🇪 [de](../../../de/docs/reference/API_REFERENCE.md) · 🇬🇷 [el](../../../el/docs/reference/API_REFERENCE.md) · 🇪🇸 [es](../../../es/docs/reference/API_REFERENCE.md) · 🇪🇪 [et](../../../et/docs/reference/API_REFERENCE.md) · 🇮🇷 [fa](../../../fa/docs/reference/API_REFERENCE.md) · 🇫🇮 [fi](../../../fi/docs/reference/API_REFERENCE.md) · 🇫🇷 [fr](../../../fr/docs/reference/API_REFERENCE.md) · 🇮🇪 [ga](../../../ga/docs/reference/API_REFERENCE.md) · 🇮🇳 [gu](../../../gu/docs/reference/API_REFERENCE.md) · 🇳🇬 [ha](../../../ha/docs/reference/API_REFERENCE.md) · 🇮🇱 [he](../../../he/docs/reference/API_REFERENCE.md) · 🇮🇳 [hi](../../../hi/docs/reference/API_REFERENCE.md) · 🇭🇷 [hr](../../../hr/docs/reference/API_REFERENCE.md) · 🇭🇺 [hu](../../../hu/docs/reference/API_REFERENCE.md) · 🇦🇲 [hy](../../../hy/docs/reference/API_REFERENCE.md) · 🇮🇩 [id](../../../id/docs/reference/API_REFERENCE.md) · 🇳🇬 [ig](../../../ig/docs/reference/API_REFERENCE.md) · 🇮🇹 [it](../../../it/docs/reference/API_REFERENCE.md) · 🇯🇵 [ja](../../../ja/docs/reference/API_REFERENCE.md) · 🇬🇪 [ka](../../../ka/docs/reference/API_REFERENCE.md) · 🇰🇭 [km](../../../km/docs/reference/API_REFERENCE.md) · 🇮🇳 [kn](../../../kn/docs/reference/API_REFERENCE.md) · 🇰🇷 [ko](../../../ko/docs/reference/API_REFERENCE.md) · 🇱🇹 [lt](../../../lt/docs/reference/API_REFERENCE.md) · 🇱🇻 [lv](../../../lv/docs/reference/API_REFERENCE.md) · 🇮🇳 [ml](../../../ml/docs/reference/API_REFERENCE.md) · 🇮🇳 [mr](../../../mr/docs/reference/API_REFERENCE.md) · 🇲🇾 [ms](../../../ms/docs/reference/API_REFERENCE.md) · 🇲🇹 [mt](../../../mt/docs/reference/API_REFERENCE.md) · 🇲🇲 [my](../../../my/docs/reference/API_REFERENCE.md) · 🇳🇵 [ne](../../../ne/docs/reference/API_REFERENCE.md) · 🇳🇱 [nl](../../../nl/docs/reference/API_REFERENCE.md) · 🇳🇴 [no](../../../no/docs/reference/API_REFERENCE.md) · 🇮🇳 [or](../../../or/docs/reference/API_REFERENCE.md) · 🇮🇳 [pa](../../../pa/docs/reference/API_REFERENCE.md) · 🇵🇭 [phi](../../../phi/docs/reference/API_REFERENCE.md) · 🇵🇱 [pl](../../../pl/docs/reference/API_REFERENCE.md) · 🇵🇹 [pt](../../../pt/docs/reference/API_REFERENCE.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/API_REFERENCE.md) · 🇷🇴 [ro](../../../ro/docs/reference/API_REFERENCE.md) · 🇷🇺 [ru](../../../ru/docs/reference/API_REFERENCE.md) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)

---

🌐 **Diller:** 🇺🇸 [English](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

OmniRoute API için temel başvuru kaynağı. Genel `/v1` yüzeyini ve en sık kullanılan yönetim uç noktalarını kapsar; makine tarafından okunabilir [`docs/openapi.yaml`](../openapi.yaml) ile `src/app/api/` altındaki rota ağacı eksiksiz kaynaklardır.

OpenAI uyumlu protokole ve sağlayıcı yetenekleri matrisine odaklanan bilgiler için
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md) belgesine bakın.

---

## İçindekiler

- [Sohbet Tamamlamaları](#chat-completions)
- [Özel Yönetilen Oturum Kiralamaları](#exclusive-managed-session-leases)
- [Gömme Vektörleri](#embeddings)
- [Görüntü Oluşturma](#image-generation)
- [Belge OCR](#document-ocr)
- [Modelleri Listeleme](#list-models)
- [Sağlayıcı Eklentisi Manifestosu](#provider-plugin-manifest)
- [Uyumluluk Uç Noktaları](#compatibility-endpoints)
- [Dosyalar API'si](#files-api)
- [Toplu İşler API'si](#batches-api)
- [Arama API'si](#search-api)
- [WebSocket Akışı](#websocket-streaming)
- [Kotalar ve Sorun Bildirimi](#quotas--issues-reporting)
- [Semantik Önbellek](#semantic-cache)
- [Pano ve Yönetim](#dashboard--management)
- [Kombinasyon Yönetimi](#combo-management)
- [Webhook'lar](#webhooks)
- [Kayıtlı Anahtarlar (Otomatik Yönetim)](#registered-keys-auto-management)
- [Ajan Protokolü](#agents-protocol)
- [Yönetim Proxy'leri](#management-proxies)
- [Dayanıklılık (genişletilmiş)](#resilience-extended)
- [Beceriler](#skills)
- [Bellek](#memory)
- [MCP Sunucusu](#mcp-server)
- [A2A Sunucusu](#a2a-server)
- [Bulut, Değerlendirmeler ve Ölçme](#cloud-evals--assess)
- [İstek İşleme](#request-processing)
- [Kimlik Doğrulama](#authentication)

---

## Sohbet Tamamlamaları

```bash
POST /v1/chat/completions
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Bir işlev yaz..."}
  ],
  "stream": true
}
```

### Özel Üstbilgiler

| Üstbilgi                 | Yön   | Açıklama                                                                                                                                                                                                                 |
| ------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-OmniRoute-No-Cache`   | İstek | Önbelleği atlamak için `true` olarak ayarlayın                                                                                                                                                                           |
| `x-omniroute-no-memory`  | İstek | Bu istek için bellek + beceri eklemeyi atlamak üzere `true` olarak ayarlayın (önbellek kullanmama davranışını yansıtır; çağrı başına belirteç/maliyet ek yükünü önler)                                                   |
| `X-OmniRoute-Progress`   | İstek | İlerleme olayları için `true` olarak ayarlayın                                                                                                                                                                           |
| `X-Session-Id`           | İstek | Harici oturum benzeşimi için kalıcı oturum anahtarı                                                                                                                                                                      |
| `x_session_id`           | İstek | Alt çizgili değişken de kabul edilir (doğrudan HTTP)                                                                                                                                                                     |
| `X-OmniRoute-Session-Id` | İstek | Çağıran tarafından sağlanan oturum/konuşma etiketi (belleği de besler). Mevcut olduğunda, oturum başına maliyet ilişkilendirmesi için `call_logs.session_tag` alanına aynen kaydedilir (#8249) — yoksa asla oluşturulmaz |
| `Idempotency-Key`        | İstek | Yinelenenleri önleme anahtarı (5 saniyelik pencere)                                                                                                                                                                      |
| `X-Request-Id`           | İstek | Alternatif yinelenenleri önleme anahtarı                                                                                                                                                                                 |
| `x-omniroute-connection` | İstek | Tek modelli bir isteği kimliğine göre tek bir sağlayıcı bağlantısına (hesaba) sabitleyin — bkz. [İstek başına hesap sabitleme](#account-pinning-per-request)                                                             |
| `X-OmniRoute-Cache`      | Yanıt | `HIT` veya `MISS` (akışsız)                                                                                                                                                                                              |
| `X-OmniRoute-Idempotent` | Yanıt | Yinelenen istek kaldırıldıysa `true`                                                                                                                                                                                     |
| `X-OmniRoute-Progress`   | Yanıt | İlerleme takibi açıksa `enabled`                                                                                                                                                                                         |
| `X-OmniRoute-Session-Id` | Yanıt | OmniRoute tarafından kullanılan etkin oturum kimliği                                                                                                                                                                     |
| `X-OmniRoute-Request-Id` | Yanıt | İstek ilişkilendirme kimliği (biliniyorsa)                                                                                                                                                                               |
| `X-OmniRoute-Version`    | Yanıt | OmniRoute derleme sürümü (her zaman mevcuttur)                                                                                                                                                                           |
| `X-OmniRoute-Cost-Saved` | Yanıt | Önbelleğin bir HIT durumunda önlediği USD tutarı (yalnızca önbellek isabetleri)                                                                                                                                          |
| `X-OmniRoute-Decision`   | Yanıt | Yönlendirme izi: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>`, birleşik stratejidir; birleşik olmayan bir istek için `single` kullanılır) — tamamlama yanıtlarında her zaman mevcuttur                  |

> Nginx notu: Alt çizgili üstbilgilere (örneğin `x_session_id`) güveniyorsanız `underscores_in_headers on;` ayarını etkinleştirin.

#### İstek başına hesap sabitleme

Bir sağlayıcının birden fazla bağlantısı (hesabı veya anahtarı) olduğunda OmniRoute normalde hesap seçme stratejisi aracılığıyla bunlardan birini seçer. Bunun yerine bir istek, `x-omniroute-connection` üstbilgisiyle belirli bir bağlantıya sabitlenebilir:

```bash
curl http://localhost:20128/v1/chat/completions \
  -H "Authorization: Bearer <OmniRoute API anahtarınız>" \
  -H "Content-Type: application/json" \
  -H "x-omniroute-connection: <connection id>" \
  -d '{"model": "codex/gpt-5.5", "messages": [{"role": "user", "content": "merhaba"}]}'
```

- **Kimlik nerede bulunur.** Kontrol panelinde sağlayıcı sayfasını açın
  (**Kontrol Paneli → Sağlayıcılar → <provider>**) ve bir bağlantı satırındaki `xxxxxxxx…`
  kimlik etiketine tıklayın — bu işlem tam bağlantı kimliğini kopyalar.
- **Hangi istekler bunu dikkate alır.** `/v1/chat/completions`, `/v1/messages` ve
  `/v1/responses` üzerindeki tek modelli istekler (`provider/model`). Kombinasyonlar başlığı yok sayar:
  bunun yerine her kombinasyon adımı için hesabı, adımın kendi bağlantısı üzerinden sabitleyin.
- **Sabitleme bir tercih değil, katı bir kuraldır.** Yalnızca sabitlenen bağlantı kullanılır.
  İstek içindeki bir hata hesabın bekleme süresini kaydeder ancak aynı sağlayıcının başka bir
  hesabına **geçiş yapmaz**.
- **Bekleme süresi ve kota, sabitlemeyi kaldırır.** Sabitlenen bağlantı bekleme süresindeyken,
  kotası tükenmişken veya bir kota politikası tarafından engellenmişken sonraki istekler, tıpkı
  sabitlenmemiş trafikte olduğu gibi sağlayıcının diğer bağlantılarına geri döner.
- **Bilinmeyen veya devre dışı bırakılmış kimlikler başarısız olur.** Sağlayıcının etkin havuzunda
  bulunmayan bir kimlik (silinmiş, devre dışı bırakılmış veya başka bir sağlayıcıya ait) uygun
  hesap bırakmaz; bu nedenle istek sessizce başka bir yere yönlendirilmek yerine başarısız olur.

Claude Code, özel başlıkları `ANTHROPIC_CUSTOM_HEADERS` üzerinden gönderir. Her proje için farklı
bir hesabı sabitlemek üzere bunu `~/.claude/settings.json` dosyasındaki `env` bloğuna veya proje
düzeyindeki bir `.claude/settings.json` dosyasına yerleştirin:

```jsonc
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://<your OmniRoute>:20128",
    "ANTHROPIC_AUTH_TOKEN": "<your OmniRoute API key>",
    "ANTHROPIC_CUSTOM_HEADERS": "x-omniroute-connection: <connection id>",
  },
}
```

Kaynak: `src/sse/handlers/chat.ts` (başlığın okunması), `src/sse/services/auth.ts` ve
`src/sse/services/sessionAffinityPin.ts` (sabitlemenin kaldırılması ve havuzda bulunmama kontrolü).

> **Maliyet telemetrisi başlıkları:** akışsız başarılı yanıtlar ayrıca `X-OmniRoute-*` maliyet telemetrisi kümesini taşır — `X-OmniRoute-Response-Cost` (USD, sabit 10 ondalık basamak; ücretsiz/fiyatlandırılmamış olanlar için `0.0000000000`), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit` ve `X-OmniRoute-Fallback-Attempts` (yalnızca > 0 olduğunda), ayrıca `X-OmniRoute-Request-Id` ve `X-OmniRoute-Version`. Bunlar sohbet tamamlamaları, `/v1/responses`, `/v1/messages` **ve medya uç noktaları** tarafından yayınlanır — `/v1/embeddings`, `/v1/images/generations`, `/v1/audio/speech`, `/v1/audio/transcriptions`, `/v1/rerank`, `/v1/videos/generations`, `/v1/music/generations` ve `/v1/moderations` (maliyet her zaman `0`). Fiyatlandırma mevcut olduğunda medya maliyeti modalite başına (görsel, saniye, karakter veya arama birimi başına) hesaplanır; aksi takdirde `0` olur (hata durumunda devam eder).

> **Önbellek isabeti maliyet semantiği:** anlamsal önbellek İSABETİNDE (`X-OmniRoute-Cache-Hit: true`) yukarı akış çağrısı yapılmaz; bu nedenle `X-OmniRoute-Response-Cost`, `0.0000000000` değerindedir (isabeti sunmanın **ek** maliyeti). Orijinal/gerçekleşmiş olacak maliyet, `X-OmniRoute-Cost-Saved` içinde ayrıca bildirilir. Faturalandırma tüketicileri `X-OmniRoute-Response-Cost` değerlerini toplamalıdır (isabetlerin maliyeti yoktur); önbellek analizleri ise `X-OmniRoute-Cost-Saved` değerlerini bir araya getirebilir.

## Özel Yönetilen Oturum Kiralamaları

Özel yönetilen oturum kiralaması, isteğe bağlı, istemci-nötr bir yönlendirme sözleşmesidir: bir aktif sahip, bir uygun OmniRoute bağlantısına sahiptir. Bir model kiralamaz, OAuth gerektirmez, belirli bir istemciyi tanımlamaz veya belirli bir sağlayıcı gerektirmez.

Kimlik doğrulayan API anahtarı `lease:exclusive` kapsamına ve açık, boş olmayan bir `allowedConnections` listesine sahip olmalıdır. Veritabanı mutasyon sınırı, anahtar oluşturma ve kısmi güncellemelerde her iki alanı birlikte uygular.

```http
POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>

{"action":"acquire","model":"glm/glm-4.6"}
```

Başarılı edinme, yenileme ve serbest bırakma yanıtları zaman damgalarını, `state`'i ve tam pozitif `generation`'ı gösterir, ancak seçilen bağlantıyı veya kimlik bilgilerini asla göstermez. Yenileme ve serbest bırakma, JSON gövdesinde generation'ı sağlar:

```json
{ "action": "renew", "generation": 1 }
```

```json
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }
```

Aktif bir kiralama sahibi, mevcut bağlaması için gizlilik açısından güvenli görüntü meta verilerini açıkça talep edebilir:

```json
{ "action": "status", "generation": 1 }
```

```json
{
  "state": "ACTIVE",
  "generation": 1,
  "acquiredAt": "2026-08-28T12:00:00.000Z",
  "renewedAt": "2026-08-28T12:00:30.000Z",
  "expiresAt": "2026-08-28T12:02:30.000Z",
  "connection": {
    "displayName": "Primary Codex",
    "provider": "codex"
  }
}
```

Bu isteğe bağlı durum eylemi, tek bir veritabanı işleminde opak sahip, kimliği doğrulanmış yönetilen API anahtarı ve tam aktif generation tarafından korunur. `displayName` yalnızca kırpılmış yapılandırılmış bağlantı adıdır; güvenli yapılandırılmış bir ad yoksa `null` olur. OmniRoute asla bir e-posta veya oluşturulmuş hesap kimliği yerine geçmez. Sağlayıcı değeri hassas olmayan bir görüntü etiketidir ve asla oluşturulmuş uyumlu sağlayıcı tanımlayıcısı değildir. Kimlik bilgileri, belirteçler, çerezler, ham bağlantı veya API anahtarı kimlikleri, sahip karmaları, sınırlama sırları ve dahili yönlendirme verileri hariç tutulur.

Yanlış anahtar, yanlış sahip, eski generation, eksik, süresi dolmuş, serbest bırakılmış ve geçersiz kılınmış aramaların tümü, bağlantı meta verileri olmadan aynı `409 LEASE_FENCE_STALE` hatasını döndürür. Kapasite bekleme yanıtını alan bir istemcinin denetleyeceği aktif bir bağlaması yoktur. Yönlendirme aktif bir kiralamayı geçiş yaptığında, aynı generation geçerli kalır ve durum atomik olarak yeni bağlamayı döndürür, asla eskisini döndürmez. Mevcut istemciler değişmeden kalır çünkü edinme, yenileme, serbest bırakma ve bekleme yanıtları önceki şekillerini korur.

Bu sunucu sözleşmesi, standart OpenAI Codex `/status`'u değiştirmez. Standart Codex şu anda model sağlayıcısını ve yerleşik kimlik doğrulama/hesap durumunu rapor eder ancak rastgele özel sağlayıcı hesap meta verilerini işlemez; daha sonraki bir istemci entegrasyonu bu eylemi çağırmalı ve `connection.displayName`'i nasıl görüntüleyeceğine karar vermelidir.

Her yönetilen çıkarım isteği daha sonra her iki kontrol başlığını da sağlar:

```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```

Tam sahip, generation, aktif bağlantı ve kimliği doğrulanmış API anahtarı, desteklenen her yukarı akış denemesinden hemen önce korunur. Sahibi ve generation'ı başka bir anahtarla tekrar oynatmak, o anahtar aynı bağlantıya izin verse bile başarısız olur. Ham sahipler kalıcı hale getirilmez, günlüğe kaydedilmez, istek anlık görüntüsünde tutulmaz veya yukarı akışa iletilmez.

Geçici çekişme, `Retry-After` ile HTTP `429` döndürür ve:

```json
{
  "state": "WAITING_FOR_CAPACITY",
  "error": { "type": "lease_error", "code": "LEASE_CAPACITY_UNAVAILABLE" },
  "reason": "NO_FREE_ELIGIBLE_CONNECTION",
  "retryAfter": 30
}
```

Bu yanıt yalnızca, sıradan uygun kümenin boş olmadığını ve her boş adayın yabancı bir aktif kiralama tarafından tutulduğunu ifade eder. Desteklenmeyen modeller/sağlayıcılar, ilke uyuşmazlığı, bekleme süresi, kota, sağlık ve diğer sıradan uygunluk hataları mevcut OmniRoute yanıtlarını korur.

### `x-omniroute-compression`

Sıkıştırma planının istek başına geçersiz kılınması. En yüksek öncelik — yönlendirme-birleşimi geçersiz kılmasını, aktif profili, otomatik tetikleyiciyi ve panel Varsayılanını yener. Değerler:

| Değer         | Etki                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------- |
| `off`         | Bu istek için sıkıştırma yok.                                                                           |
| `default`     | Panelden türetilmiş Varsayılan profil (aktif profili yok sayar). Kayıplı motorlar kapalı bırakılır.     |
| `safe`        | Yalnızca tekilleştirme ve boşluk katlama.                                                               |
| `allow-lossy` | Özetler ve stil yeniden yazmaları dahil olmak üzere bu istek için operatör planını koruyun.             |
| `engine:<id>` | Etkinleştirildiğinde tek bir motor, örn. `engine:rtk`. Bu motor için istek başına katılım.              |
| `<combo>`     | Adlandırılmış bir birleşim, önce ada göre (büyük/küçük harf duyarsız), sonra kimliğe göre eşleştirilir. |

Notlar:

- Bilinmeyen değerler yok sayılır (istek asla reddedilmez); çözümleme normal operatör önceliğine düşer.
- Birden fazla birleşim aynı adı paylaşıyorsa, belirleyici bir eşleşme için birleşim **kimliğini** geçirin.
- Adı `off` veya `default` olan bir birleşim adıyla seçilemez (bu anahtar kelimeler önce yorumlanır); böyle bir birleşimi kimliğiyle referans alın.
- Ana sıkıştırma anahtarı sert bir geçittir: sıkıştırma global olarak devre dışı bırakıldığında, bu başlık onu etkinleştiremez.

Uygulanan plan yanıt başlığında geri yankılanır:

```
X-OmniRoute-Compression: <mode>; source=<source>
```

burada `<source>`, `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` veya `off` değerlerinden biridir.

---

## Gömme Vektörleri

```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "nebius/Qwen/Qwen3-Embedding-8B",
  "input": "The food was delicious"
}
```

Kullanılabilir sağlayıcılar: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

Katalog kimlikleri `provider/model` biçimindedir (örnek: `jina-ai/jina-embeddings-v5-omni-small`). Kayıt defterinde yer alan yalın Jina model kimlikleri de (örneğin `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) çözümlenir. Jina embed/rerank/classify/segment işlemleri önce kontrol panelindeki `jina-ai` kimlik bilgilerini kullanır; `JINA_AI_API_KEY`, yalnızca kontrol paneli anahtarı bulunmadığında yedek olarak kullanılır. `jina-reader` kartı yalnızca Reader / `r.jina.ai` içindir (`POST /v1/web/fetch`) ve hiçbir zaman gömme vektörü veya yeniden sıralama hizmeti sunmaz.

Çok modlu desteğe sahip olduğunu belirten kayıt defteri modelleri, sağlayıcıdan bağımsız en fazla 32 yapılandırılmış
öğeyi de kabul eder. Medya öğesi türleri `text`, `image`, `audio`, `video` ve `document` şeklindedir. Bunların medya `source`
değeri ya `{"type":"url","url":"https://..."}` ya da
`{"type":"base64","data":"...","media_type":"..."}` biçimindedir.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`
ve aile diğer adı `jina-ai/jina-embeddings-v5-omni` → omni-small), Jina'nın yerel
EmbeddingsV5Request belgelerini de kabul eder ve bunları **değiştirmeden** `https://api.jina.ai/v1/embeddings` adresine iletir:

```json
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}
```

Yerel `{ image | audio | video | pdf }` değerleri herkese açık bir HTTPS URL'si, bir `data:` URI'si veya ham
base64 olabilir. OmniRoute bu nesneleri dizelere dönüştürmez veya yerel görüntü URL'lerini getirmez — herkese açık
medyayı Jina'nın kendisi alır. Ek Jina alanları (`task`, `normalized`, `truncate`, `embedding_type`)
iletilir. Yalnızca metin destekleyen Jina SKU'ları, metin dışı belgeleri reddetmeye devam eder.

Güvenlik ve aktarım sınırları:

- Uzak medya URL'leri herkese açık HTTPS olmalıdır. Kurallı `{type,source:url}` öğeleri
  sunucu tarafında alınır (yönlendirme yeniden doğrulaması, zaman aşımı, boyut sınırları, herkese açık DNS, bağlantı sabitleme) ve
  sağlayıcı çağrısından önce satır içine eklenir. Jina'ya özgü `{image:"https://..."}` öğeleri, aynı herkese açık HTTPS denetiminden
  sonra olduğu gibi iletilir; URL'yi Jina alır.
- Satır içi base64 medya, öğe başına çözümlenmiş 8 MiB ve istek genelinde çözümlenmiş 16 MiB ile sınırlıdır.

Sağlayıcı dönüşümü (kurallı öğeler hiçbir zaman değiştirilmeden iletilmez):

- Jina çok modlu modelleri: Her üst düzey öğe, satır içi medya için veri URI'leri kullanan,
  modalite anahtarlı tek bir nesneye (`text` / `image` / `audio` / `video` / `pdf`) dönüştürülür; her
  üst düzey öğe için bir vektör oluşturulur.
- Gemini Embedding 2 ailesi: Bir üst düzey dizi, `content.parts` (`text` veya `inline_data`)
  içeren tek bir yerel `models/{model}:embedContent` isteğine dönüştürülür.
- llama.cpp (`llama-cpp/<model>`, yerel sunucunun yüklediği herhangi bir model): Kurallı `text` öğeleri
  düz dizelere, `image` / `audio` / `video` öğeleri ise satır içi verilerle llama-server'ın sohbet içeriği parçalarını (`image_url`,
  `wav` / `mp3` / `flac` biçimli `input_audio`, `input_video`) kullanan birer
  `{"content": [part]}` nesnesine dönüştürülür; her üst düzey öğe için bir vektör oluşturulur. Sunucu `--embedding --mmproj …`
  ile çalıştırılmalıdır; projektör olmadan medyayı sunucunun kendisi reddeder. `document` desteklenmez.
- Açık modalite meta verileri bulunmayan bilinmeyen/dinamik modeller, yapılandırılmış girdiyi HTTP 400 ile reddeder.

```json
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}
```

Desteklenmeyen model/modalite birleşimleri, öğeyi dönüştürmeye zorlamak yerine HTTP 400 döndürür. Eski dize/belirteç
isteklerindeki girdi dışı uzantı alanları, değiştirilmeden aktarılmaya devam eder.

```bash
# Tüm gömme vektörü modellerini listele
GET /v1/embeddings
```

---

## Görsel Oluşturma

```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "openai/gpt-image-2",
  "prompt": "Dağların üzerinde güzel bir gün batımı",
  "size": "1024x1024"
}
```

Kullanılabilir sağlayıcılar arasında OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (yerel) ve ComfyUI (yerel) bulunur.

`n`, `data[]` içinde `n` adet görsel döndürür. Üst API'si çağrı başına bir görsel döndüren sağlayıcılar
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI) için en fazla 4'ü eşzamanlı olmak üzere `n` ayrı üst API çağrısı yapılır. Sabit
bir `seed`, çağrı dizinine göre artırılır (`seed`, `seed + 1`, …); böylece görseller farklı olurken
yeniden üretilebilirlik korunur. `n` en fazla 10 olabilir. Herhangi bir çağrı başarısız olursa isteğin
tamamı başarısız olur. Dağıtımlı çağrı biçimlerinin listesi
`open-sse/handlers/imageGeneration/fanOut.ts` içindeki `SINGLE_IMAGE_FANOUT_FORMATS` sabitinde yer alır.

ZenMux, mevcut API anahtarı bağlantısını yeniden kullanır ve `zenmux/` veya `zm/` öneklerini kabul eder:

- `zenmux/openai/gpt-image-2`, ZenMux'ın OpenAI Images API'sini kullanır. Seçenekler arasında `size`,
  `quality`, `n`, `output_format`, `output_compression`, `background` ve `response_format` bulunur.
- `zm/meta/muse-image-1.0` gibi diğer yayıncılar, ZenMux'ın Vertex AI `:predict`
  uç noktasını kullanır. `n`, `sampleCount` alanına; `aspect_ratio`, `aspectRatio` alanına; `image_size`
  (`1K`, `2K`, `4K`) ise `sampleImageSize` alanına eşlenir. Piksel cinsinden bir `size` yalnızca en-boy oranını
  belirtir; piksel boyutları garanti edilmez. Desteklenen oranlar, çözünürlükler ve adetler modele göre değişir.
- `zm/inclusionai/ming-image-0.1-design` kendi boyutlarını seçer. `size`,
  `aspect_ratio` ve `image_size` değerlerini belirtmeyin; açıkça belirtilen değerler HTTP 400 döndürür. PNG, JPEG ve WebP
  biçimleri `output_format` ile istenebilir.

Bu entegrasyon, referans görsel düzenlemeyi değil, metinden görsel oluşturmayı destekler. Vertex
çıktısı `data[].b64_json` biçimine normalleştirilir; `response_format: "url"`, yalnızca görsel baytları
mevcut olduğunda üst API'den bir HTTPS URL'si veya base64 veri URL'si döndürür. Boş/filtrelenmiş çıktılar,
boş bir başarılı yanıt yerine hata döndürür. Model erişimi ZenMux hesabına bağlıdır.
Bkz. [ZenMux Vertex API'si](https://docs.zenmux.ai/api/vertexai/generate-images) ve
[OpenAI Images API'si](https://docs.zenmux.ai/api/openai/generate-an-image).

```bash
# Tüm görsel modellerini listele
GET /v1/images/generations
```

---

## Belge OCR

```bash
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json

{
  "model": "mistral/mistral-ocr-latest",
  "document": {
    "type": "document_url",
    "document_url": "https://example.com/invoice.pdf"
  }
}
```

`model`, bir `provider/model` öneki aracılığıyla OCR sağlayıcısını seçer; yalnızca model kimliği (ör.
`mistral-ocr-latest`) belirtilirse kayıtlı sağlayıcısına çözümlenir ve `model` atlanırsa varsayılan olarak
Mistral (`mistral-ocr-latest`) kullanılır. Kayıtlı sağlayıcılar (`open-sse/config/ocrRegistry.ts`):

| Sağlayıcı kimliği             | Model kimliği        | `model` değeri                                                    | Notlar                                                                                                                       |
| ----------------------------- | -------------------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (veya yalnızca `mistral-ocr-latest`) | Eşzamanlı — yanıt, tek üst akış çağrısından doğrudan döndürülür.                                                             |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                       | Eşzamansız üst akış (`analyze` + yoklama) — aşağıya bakın.                                                                   |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                           | Eşzamanlı, Vertex AI'ın `openapi/chat/completions` iş ortağı uç noktası üzerinden — kimlik doğrulama/URL için aşağıya bakın. |

Üç sağlayıcı da Mistral ile aynı yapıdaki gövdeyle yanıt verir:

```json
{
  "pages": [{ "index": 0, "markdown": "# Extracted text..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### Azure Document Intelligence yoklama akışı

Azure Document Intelligence'ın `analyze` API'si eşzamansızdır: ilk istek, gövde yerine bir
`Operation-Location` başlığı döndürür ve sonuç için yoklama yapılması gerekir. İşleyici
(`open-sse/handlers/ocr.ts`) bu URL'yi en fazla 30 deneme boyunca saniyede bir yoklar, `ok` olmayan
bir yoklama yanıtında veya `"failed"` durumunda hızlıca başarısız olur (yoklamaya devam etmez) ve
deneme bütçesi tükendikten sonra işlem hâlâ devam ediyorsa `504` döndürür. Nihai Azure yanıtı,
çağırana döndürülmeden önce Mistral tarafından kullanılan aynı `pages`/`markdown` yapısına
normalleştirilir; böylece istemci kodunun sağlayıcıya özel durumları ele alması gerekmez.

### Vertex AI DeepSeek OCR kimlik doğrulaması ve uç nokta çözümlemesi

`vertex-deepseek-ocr`, OmniRoute'un sohbet/görsel trafiği için zaten desteklediği aynı Vertex AI
kimlik doğrulamasını (`open-sse/executors/vertex.ts`) yeniden kullanır: bağlantının API anahtarı,
JWT-bearer akışı aracılığıyla kısa ömürlü bir OAuth erişim belirteciyle değiştirilen bir Service
Account JSON kimlik bilgisi veya olduğu gibi kullanılan, önceden oluşturulmuş bir OAuth erişim
belirtecidir. Üst akış uç noktası URL'si, bağlantının projesi ve bölgesi kullanılarak oluşturulan
Vertex'ın genel `openapi/chat/completions` iş ortağı uç noktasıdır — açıkça belirtilen
`providerSpecificData.project`/`providerSpecificData.region` her zaman önceliklidir; aksi takdirde
proje, Service Account JSON içindeki `project_id` değerinden türetilir ve bölge varsayılan olarak
`us-central1` olur. Her iki çözümleme de `open-sse/handlers/ocr.ts` içinde
(`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) gerçekleştirilir ve `handleOcr` işlevine
aktarılmadan önce `src/app/api/v1/ocr/route.ts` tarafından kullanılır.

---

## Modelleri Listeleme

```bash
GET /v1/models
Authorization: Bearer your-api-key

→ Tüm sohbet, gömme ve görüntü modellerini + kombinasyonları OpenAI biçiminde döndürür
```

### Model kimliği ön ekleri (`?prefix=`)

Çoğu model bir **sağlayıcı ön eki** altında sunulur. Hangi ön eki alacağınız
`MODELS_CATALOG_PREFIX_MODE` özellik bayrağı tarafından belirlenir ve bir sorgu parametresiyle
**istek başına** geçersiz kılınabilir — bu, diğer herkes için sunucu genelindeki ayarı değiştirmeden
temiz bir liste isteyen istemciler açısından kullanışlıdır:

```bash
GET /v1/models?prefix=alias        # model başına bir kimlik — kısa takma ad ön eki
GET /v1/models?prefix=dual         # her iki biçim (sunucu varsayılanı)
GET /v1/models?prefix=canonical    # yalnızca tam sağlayıcı kimliği ön eki
```

| Mod         | Üretilen                                                 | Notlar                                                                                                                                                                                                           |
| ----------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **ve** `claude/claude-sonnet-4-6` | **Varsayılan.** Her iki kimlik de aynı modele yönlendirilir; iki biçimden birini sabit kodlamış istemci yapılandırmalarının çalışmaya devam etmesi için korunur. Kataloğun boyutunu yaklaşık iki katına çıkarır. |
| `alias`     | `cc/claude-sonnet-4-6`                                   | Model başına bir girdi. Ayrı bir takma adı olmayan sağlayıcılar da girdilerini sunmaya devam eder; dolayısıyla hiçbir şey kaybolmaz.                                                                             |
| `canonical` | `claude/claude-sonnet-4-6`                               | Tam sağlayıcı kimliği ön eki altında model başına bir girdi. Ayrı bir takma adı olmayan sağlayıcılar (ör. `antigravity/…`, `agy/…`) burada da tek kimliklerini sunar; dolayısıyla hiçbir şey kaybolmaz.          |

`dual` modundaki bir yansıtılmış girdi, sorgu parametresi olmadan da tanınabilir: birincil kimliği
işaret eden bir `parent` alanı taşır.

Model seçici oluşturan istemciler `?prefix=alias` istemelidir — [OmniCopilot VS Code uzantısı](../guides/VSCODE-COPILOT.md)
bunu yapar.

### Keşif filtreleri (`?capability=`, `?min_context=`, `?kind=`, `?q=`)

`GET /v1/models`, isteğe bağlı keşif filtrelerini kabul eder. Bunların hiçbiri olmadan yanıt
değişmez. Bu filtreler, çağıranın hâlihazırda görebildiği kataloğu daraltır (önce API anahtarı izinleri
uygulanır) ve OpenAI tarzı `limit` / `after` sayfalamasından önce çalışır:

```bash
GET /v1/models?capability=vision&capability=tool_calling   # listelenen her yetenek doğru olmalıdır
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # katalog `type` değeri; bu değere sahip olmayan satırlar `chat` olarak kabul edilir
GET /v1/models?q=sonnet&limit=10                           # kimlik veya ad üzerinde büyük/küçük harfe duyarsız eşleşme
```

| Parametre     | Değerler                                                                                            |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `capability`  | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` |
| `min_context` | negatif olmayan tam sayı; `context_length` ile karşılaştırılır                                      |
| `kind`        | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video`                     |
| `q`           | 1–200 karakter                                                                                      |

Bilinmeyen bir değer veya negatif olmayan bir tam sayı niteliği taşımayan bir `min_context` (örneğin `1.5`),
HTTP `400` döndürür ve mesajda geçerli değerler listelenir. Uygulama:
`src/app/api/v1/models/catalogFilters.ts`.

### Model kısa listesi (`POST /v1/models/query`)

`POST /v1/models/query`, `GET /v1/models` ile aynı katalogdan, aynı kimlik doğrulaması ve anahtar
başına görünürlük kurallarıyla kısa ve belirlenimci bir liste döndürür:

```bash
POST /v1/models/query
Authorization: Bearer your-api-key
Content-Type: application/json

{ "capabilities": ["vision", "tool_calling"], "min_context": 128000, "max_output": 16000,
  "kind": "chat", "q": "gpt", "owned_by": "openai", "exclude": ["openai/gpt-4o"], "limit": 5 }

→ { "object": "list", "data": [ ...models ] }
```

Her alan isteğe bağlıdır. `capabilities` ve `exclude`, bir dizi veya virgülle ayrılmış bir dize kabul eder;
`max_output`, `max_output_tokens` ile karşılaştırılır. Sonuçlar önce `owned_by`, ardından `id` değerine
göre sıralanır. `limit` varsayılan olarak `20` değerini alır ve `100` üzerindeki değerler `100` ile
sınırlandırılır. Geçersiz JSON, bilinmeyen bir alan veya geçersiz bir değer HTTP `400` döndürür.

### Ayrı ayrı gizlenen sohbet modelleri

Sağlayıcı sayfasında **Gizli** olarak işaretlenen bir model katalogdan çıkarılır ve açıkça
istendiğinde HTTP `404` / `model_not_found` ile reddedilir. Denetim; sağlayıcı takma adları,
uyumlu sağlayıcı düğümü ön ekleri ve bağlantı varsayılanları dâhil olmak üzere çözümlenmiş
sağlayıcıyı ve modeli kullanır. Bir kombinasyon, gizli hedefleri atlar ve görünür bir kardeşi
kullanabilir; çalıştırılabilir hiçbir hedef kalmadığında aynı hata kodunu döndürür. Gizliliğin
kaldırılması bir sonraki istekte yürürlüğe girer. Yalnızca görüntüye özgü görünürlük geçersiz
kılmaları, aynı kimliğe sahip sohbet modelini gizlemez.

Bu ayrı model ayarı, açık gönderimi korurken katalogda sunulan modelleri ve otomatik yönlendirme
adaylarını filtreleyen [model gösterimi izin/ret listelerinden](../routing/MODEL_EXPOSURE_LIST.md)
ayrıdır. API anahtarı model izinleri bağımsız olarak uygulanmaya devam eder. Varsayılan katalog
ön eki modu `dual` olarak kalır.

### Düşünmeyen model varyantları

Düşünme yeteneğine sahip Claude modelleri için `/v1/models`, kimliği `claude-3-omniroute-no-thinking/`
ile başlayan bir **düşünmeyen** varyantı da sunar:

```
claude-3-omniroute-no-thinking/<provider>/<model>
```

Bu kimliğin seçilmesi (ör. her zaman bir `thinking` bloğu ekleyen bir Claude Code yapılandırmasında), akıl yürütme devre dışı bırakılarak gerçek `<provider>/<model>` değerine geri çözümlenir — `/v1/messages` yolunda `thinking:{type:"disabled"}` kullanılır veya `/v1/chat/completions` yolunda `reasoning`/`reasoning_effort` alanları kaldırılır. Varyant yalnızca thinking özelliğini destekleyen **ve** `disabled` değerini kabul eden Claude ailesi modelleri için listelenir (bu nedenle, örneğin `disabled` değerini reddeden yalnızca uyarlanabilir modeller hariç tutulur). Operatörler, `ModelSpec.noThinkingAlias` aracılığıyla varyantı model bazında zorla etkinleştirebilir veya devre dışı bırakabilir.

---

## Sağlayıcı Eklentisi Manifesti

```bash
GET /api/v1/provider-plugin-manifest
```

Bifrost, CLIProxyAPI ve gelecekteki sidecar yönlendiricileri tarafından kullanılan, JSON açısından güvenli sağlayıcı eklentisi manifestini döndürür. Yanıt, TypeScript sağlayıcı kayıt defterinden oluşturulur ve OAuth istemci sırlarını, çalışma zamanı ortam çözümlemesini, yürütücü işlevlerini, istek başlıklarını ve hesap verilerini bilinçli olarak hariç tutar.

Bir sidecar süreç dışında çalıştığında ve `open-sse/config/providerPluginManifestRegistry.ts` dosyasını doğrudan içe aktaramadığında bu uç noktayı kullanın.

---

## Uyumluluk Uç Noktaları

| Yöntem | Yol                                       | Biçim                                      |
| ------ | ----------------------------------------- | ------------------------------------------ |
| POST   | `/v1/chat/completions`                    | OpenAI                                     |
| POST   | `/v1/messages`                            | Anthropic                                  |
| POST   | `/v1/responses`                           | OpenAI Responses                           |
| POST   | `/v1/embeddings`                          | OpenAI                                     |
| POST   | `/v1/images/generations`                  | OpenAI Images                              |
| POST   | `/v1/images/edits`                        | OpenAI Images (düzenleme/inpainting)       |
| POST   | `/v1/videos/generations`                  | OpenAI tarzı video oluşturma               |
| POST   | `/v1/music/generations`                   | OpenAI tarzı müzik oluşturma               |
| POST   | `/v1/audio/transcriptions`                | OpenAI Audio (STT)                         |
| POST   | `/v1/audio/speech`                        | OpenAI TTS (ses gövdesi döndürür)          |
| POST   | `/v1/rerank`                              | Cohere/Voyage tarzı yeniden sıralama       |
| POST   | `/v1/classify`                            | Jina sınıflandırma (`api.jina.ai`)         |
| POST   | `/v1/segment`                             | Jina bölümleyici (`segment.jina.ai`)       |
| POST   | `/v1/moderations`                         | OpenAI Moderations                         |
| GET    | `/v1/models`                              | OpenAI                                     |
| POST   | `/v1/models/query`                        | Filtrelenmiş model kısa listesi            |
| POST   | `/v1/messages/count_tokens`               | Anthropic                                  |
| GET    | `/v1beta/models`                          | Gemini                                     |
| POST   | `/v1beta/models/{...path}`                | Gemini generateContent                     |
| POST   | `/v1/api/chat`                            | Ollama                                     |
| GET    | `/api/v1/vscode/{token}/`                 | OpenAI katalog takma adı                   |
| GET    | `/api/v1/vscode/{token}/models`           | OpenAI model takma adı                     |
| POST   | `/api/v1/vscode/{token}/chat/completions` | OpenAI belirteçli takma ad                 |
| POST   | `/api/v1/vscode/{token}/responses`        | OpenAI Responses belirteçli takma ad       |
| POST   | `/api/v1/vscode/{token}/api/chat`         | Ollama belirteçli takma ad                 |
| GET    | `/api/v1/vscode/{token}/api/tags`         | Ollama etiketleri için belirteçli takma ad |

Tüm POST rotaları aynı yapıyı izler: `Bearer your-api-key` + Zod ile doğrulanmış JSON gövdesi (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` vb.; bkz. `src/shared/validation/schemas.ts`). Şema doğrulaması başarısız olduğunda 4xx döndürülür.

`Authorization: Bearer ...` ekleyemeyen istemciler için OmniRoute, aşağıda belgelenen özel `/api/v1/vscode/{token}/...` uç noktalarının yanı sıra sorgu dizesi uyumluluğu (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) aracılığıyla URL içinde API anahtarlarını da kabul eder.

```bash
# Yeniden sıralama (bulut kayıt sağlayıcısı veya "<prefix>/<model>" biçiminde OpenAI uyumlu bir sağlayıcı düğümü)
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina sınıflandırma (Foundation API kimlik bilgileri)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina bölümleyici
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina araması (s.jina.ai; sağlayıcı takma adları: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderasyonlar
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — audio/mpeg (veya istenen biçimde) gövde döndürür
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS bir dil ve ses gerektirir: `language` varsayılan olarak "en" değerini alır; eksik
# bir ses veya OpenAI standart ses adı (alloy, nova, …), "Adrian" değerine dönüşür
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# Görüntü düzenleme (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Video / müzik oluşturma (sağlayıcı ön ekli model kimliği)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **Yeniden sıralama sağlayıcı düğümleri:** `POST /v1/rerank`, `<node-prefix>/<model>` biçiminde
> adreslenen OpenAI uyumlu sağlayıcı düğümlerine (oMLX, vLLM, Infinity, bir ağ geçidinin arkasındaki
> TEI, …) de yönlendirme yapar. Geri döngü düğümleri (`localhost`, `127.0.0.1`, `172.16.0.0/12`)
> her zaman uygundur; operatörün `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` içinde listelediği ana makine
> adları da uygundur (ör. `http://reranker:8080/v1` gibi bir Docker/Compose hizmet adı; bunlara
> doğrudan erişilir, hiçbir zaman `HTTP(S)_PROXY` veya bir bağlantıya sabitlenmiş proxy üzerinden
> erişilmez). Diğer ana makinelerdeki düğümler — bir LAN makinesi veya Tailscale eş düğümü —
> yalnızca operatör `RERANK_REMOTE_PROVIDER_NODES` özellik bayrağını etkinleştirdiğinde **ve**
> düğümün temel URL'si sağlayıcının giden URL politikasını
> (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`) karşıladığında
> uygundur. Bellek motorunun yeniden sıralama adımı bu rotayı geri döngü üzerinden çağırır;
> dolayısıyla Bellek ayarlarındaki `rerankProviderModel` için de aynı kural geçerlidir.
>
> **Yerel sunucu biçimleri:** düğüm önce `<base>/v1/rerank`, 404 durumunda ise `<base>/rerank`
> (Infinity, TEI) üzerinden çağrılır. Yukarı akış gövdesi hem Cohere/OpenAI yazımını (`documents`,
> `return_documents`) hem de TEI yazımını (`texts`, `return_text`) taşır ve yukarı akış yanıtı
> Cohere zarfına normalleştirilir: TEI'nin yalın `[{index, score, text}]` biçimi, ince ağ
> geçitlerinden gelen `{results: [{index, score}]}` ve Voyage tarzı `{data: [...]}` biçimlerinin
> tümü istemciye puana göre sıralanmış ve `top_n` ile sınırlandırılmış
> `{results: [{index, relevance_score, document?}]}` olarak döner.

> **Sağlayıcı düğümü keşfi:** OpenAI uyumlu bir sağlayıcı düğümündeki modeller, düğüm öneki altında
> `GET /v1/models` içinde görünür. Uç nokta meta verisi taşımayan satırlar (yerel `/v1/models`
> listelemelerinde tipik olduğu üzere) düğümün `apiType` değerini devralır; böylece varsayılan olarak
> sohbet türüne ayarlanmak yerine bir `embeddings` düğümünün modelleri `type: "embedding"`, bir
> `rerank` düğümünün modelleri ise `type: "rerank"` olur. Eşitlenmiş veya elle eklenmiş bir
> satırdaki açık `supportedEndpoints` değeri yine de önceliklidir.

### Özel Sağlayıcı Rotaları

```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```

Eksikse sağlayıcı öneki otomatik olarak eklenir. Eşleşmeyen modeller `400` döndürür.

---

## Files API

Toplu girdi/çıktı ve dosya amacıyla yüklemeler için OpenAI uyumlu dosya uç noktası.

| Yöntem | Yol                      | Açıklama                                                                                                          |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Dosya yükler (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — en fazla 512 MiB |
| GET    | `/v1/files`              | Kimliği doğrulanmış API anahtarına ait dosyaları listeler                                                         |
| GET    | `/v1/files/[id]`         | Bir dosyanın meta verilerini getirir                                                                              |
| DELETE | `/v1/files/[id]`         | Bir dosyayı siler                                                                                                 |
| GET    | `/v1/files/[id]/content` | Ham dosya gövdesini akış olarak geri gönderir                                                                     |

**Kimlik doğrulama:** Bearer API anahtarı — dosyaların kapsamı `getApiKeyRequestScope` aracılığıyla API anahtarı bazında belirlenir. Bir anahtar
yalnızca kendi dosyalarını görür, indirir ve siler; anahtarı olmayan bir pano oturumu tüm
örneği okur; sahibi olmayan bir dosyaya (anonim veya pano oturumu üzerinden yüklenmiş) oturum dışındaki her
çağıranın erişimi reddedilir. `GET /v1/files`, `REQUIRE_API_KEY=false` olduğunda bile anonim bir çağıranı ve
çözümlenemeyen, sunulmuş bir anahtarı, tüm kiracıların dosyalarını listelemek yerine `401` ile
reddeder (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

OpenAI uyumlu toplu işleme.

| Yöntem | Yol                       | Açıklama                                                                                                                  |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | Toplu iş oluşturur — gövde `v1BatchCreateSchema` tarafından doğrulanır (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | Toplu işleri listeler                                                                                                     |
| GET    | `/v1/batches/[id]`        | Toplu iş durumunu ve `request_counts` değerini getirir                                                                    |
| DELETE | `/v1/batches/[id]`        | Tamamlanmış/başarısız olmuş bir toplu işi siler                                                                           |
| POST   | `/v1/batches/[id]/cancel` | Devam eden bir toplu işi iptal eder                                                                                       |

**Kimlik doğrulama:** Bearer API anahtarı. Toplu işlerin kapsamı, dosyalarla aynı üç yönlü kural kapsamında
API anahtarı bazında belirlenir: yalnızca kendi anahtarı, örnek genelinde pano oturumu, sahibi null olan kayıtlara ise oturum dışındaki her
çağıranın erişimi reddedilir (getirme, silme, iptal etme ve oluşturma sırasındaki `input_file_id` denetimi).
`GET /v1/batches`, `REQUIRE_API_KEY=false` olduğunda bile anonim bir çağıranı `401` ile reddeder.

---

## Search API'si

Web/arama sağlayıcısı soyutlaması (Tavily, Brave, Exa, Serper vb.).

| Yöntem | Yol                    | Açıklama                                                                                                     |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| GET    | `/v1/search`           | Yapılandırılmış arama sağlayıcılarını ve yeteneklerini listeler                                              |
| POST   | `/v1/search`           | Bir arama sorgusu çalıştırır — gövde `v1SearchSchema` ile doğrulanır, önbelleğe alma/birleştirmeyi destekler |
| GET    | `/v1/search/analytics` | Sağlayıcı başına isabet/gecikme/önbellek istatistikleri                                                      |

**Kimlik doğrulama:** Bearer API anahtarı (`extractApiKey` + `isValidApiKey`). Arama politikası `enforceApiKeyPolicy` aracılığıyla uygulanır.

### Exa ve Tavily `provider_options`

Exa ve Tavily, sağlayıcıya özgü alanları ad alanlı bir paketten okur:
`provider_options.exa` (veya `provider_options["exa-search"]`) ve `provider_options.tavily`
(veya `provider_options["tavily-search"]`). Yalnızca aşağıdaki anahtarlar iletilir. Her biri
`open-sse/handlers/search/providerOptionsPassthrough.ts` içindeki kendi Zod şemasına göre
kontrol edilir ve yanlış türdeki bir anahtar kaldırılır. Kimlik doğrulama, temel URL,
`stream` ve `outputSchema` dâhil olmak üzere diğer tüm anahtarlar yok sayılır. Diğer sağlayıcılar
tarafından kullanılan düz anahtarlar (`cx`, `depth`, ...) eskisi gibi çalışır.

| Sağlayıcı | Üst düzey alanlar                                                                                                                                                                                                                                                                                                                                                         | İç içe                                                                                                                                                                     |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Exa       | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (düz ilkel değerler), `startPublishedDate`, `endPublishedDate`                                                                                                                                                                                           | `contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours}` varsayılan `{ text: true, highlights: true }` üzerine birleştirilir |
| Tavily    | `search_depth`, `chunks_per_source`, `time_range`, `start_date`, `end_date`, `include_published_date`, `filter_by_published_date`, `include_answer`, `include_raw_content`, `include_images`, `include_image_descriptions`, `include_favicon`, `include_domains_mode`, `language`, `filter_by_language`, `auto_parameters`, `exact_match`, `include_usage`, `safe_search` | —                                                                                                                                                                          |

Genel alanlar her zaman önceliklidir: `query`, `max_results`, `filters` (alan adları), `country` ve
`search_type` değerinden türetilen konu. Exa'da `search_type: "news"`, `category: "news"` değerini
korur. Tavily ayrıca `search_type: "finance"` (`topic: "finance"`) değerini de kabul eder.

Genel `time_range` artık her iki sağlayıcıya da ulaşır: Exa `startPublishedDate` (ISO
zaman damgası), Tavily ise `start_date` (`YYYY-MM-DD`) alır. `provider_options` içindeki açıkça
belirtilmiş bir tarih, eşlenmiş olanı geçersiz kılar.

Exa sonuçları `id`, `highlight_scores`, `summary`, `subpages`, `entities` ve `extras` alanlarını
`provider_raw` içinde tutar. Tavily sonuçları `images` ve `favicon` alanlarını tutar.

Maliyet hesaplaması hâlâ düz `costPerQuery` kayıt defteridir. Tavily,
`search_depth: "advanced"` için çağrı başına daha fazla kredi ücretlendirir ve bu fark
`usage.search_cost_usd` değerine yansıtılmaz.

---

## Web Fetch API

Yapılandırılmış bir web-fetch sağlayıcısı (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract) aracılığıyla bir URL'den içerik çıkarır.

Parallel Extract (`parallel-search`, Parallel Search ile aynı API anahtarı) yalnızca Markdown döndürür — diğer tüm `format` değerleri `400` ile sonuçlanır — ve içeriği 100.000 karakterle sınırlar. Hedef sayfanın kendisi çıkarılamadığında üst sağlayıcı bunu HTTP 200 yanıtı içinde bildirir; OmniRoute ise bunu sabit bir mesajla `422` olarak sunar.

| Yöntem | Yol             | Açıklama                                                             |
| ------ | --------------- | -------------------------------------------------------------------- |
| POST   | `/v1/web/fetch` | Bir URL'yi getirir/ayıklar — gövde `v1WebFetchSchema` ile doğrulanır |

**Kimlik doğrulama:** Bearer API anahtarı (`extractApiKey` + `isValidApiKey`). Politika `enforceApiKeyPolicy` aracılığıyla uygulanır.

**Kota duyarlı geri dönüş (#8297):** Açıkça bir `provider` belirtilmediğinde havuz
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search`) sabit
öncelik sırasıyla (önce doldurma) dolaşılır — hız sınırına ulaşmış ancak yapılandırılmış bir sağlayıcı, isteği kısa devre etmek yerine atlanır ve yeniden denenebilir/kotayla ilgili bir üst sağlayıcı hatası
(HTTP 429 her zaman; Firecrawl/Tavily/TinyFish'in kota türü ücretsiz katmanları için 402/403 —
Jina Reader için değil ve düz bir 400 hatalı istek için hiçbir zaman değil), istek sırasında kimlik bilgileri bulunan ve henüz denenmemiş bir sonraki sağlayıcıya geçilmesine neden olur. Havuzdaki tüm sağlayıcılar
tükendiğinde uç nokta, önceki genel `400` yerine tek bir `429` (`Retry-After`
üstbilgisiyle) döndürür. Açıkça bir `provider`
istendiğinde **sessiz** geri dönüş yapılmaz — hız sınırına ulaşmış veya hata veren açık
sağlayıcının kendi hatası iletilir (hız sınırına ulaşılmışsa `429`, aksi hâlde üst sağlayıcının
durum kodu).

---

## WebSocket Akışı

```bash
GET /v1/ws?handshake=1
```

Bir WebSocket yükseltme el sıkışmasını doğrular ve kablo protokolü örnek mesajlarını (`request`, `cancel`) döndürür. Gerçek WS çerçeveleri, Next.js rota tablosunun dışında paketlenmiş WS sunucusu tarafından işlenir.

**Kimlik doğrulama:** El sıkışma sırasında Bearer API anahtarı.

### WebSocket üzerinden Responses API (yalnızca codex)

```bash
# HTTP API'siyle aynı ana makine:bağlantı noktası (varsayılan 20128); bağlantıyı yükseltin:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (veya: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# İlk çerçeve MUTLAKA response.create olmalıdır:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

WebSocket üzerinden Responses API proxy'si **yalnızca `codex`e** (ChatGPT
arka ucu) bağlıdır. API/pano ile aynı bağlantı noktasında `/v1/responses`,
`/responses` ve `/api/v1/responses` yollarını dinler. İlk `response.create` çerçevesinde
dahili `codex-responses-ws` köprüsü aracılığıyla kimlik doğrular ve hazırlık yapar, bir
codex OAuth bağlantısı seçer ve `wreq-js` aktarımı üzerinden `wss://chatgpt.com/backend-api/codex/responses`
adresine tünel oluşturur. **Codex dışındaki modeller reddedilir** (`codex_ws_provider_required`).
Kota paylaşımlı yönlendirme için `model: "qtSd/<group>/codex/<model>"` kullanın. Uygulama
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`
içindedir.

**Kimlik doğrulama:** El sıkışma sırasında Bearer API anahtarı. Paketlenmiş HTTP sunucusu (`server-ws.mjs`)
etkin giriş noktası olmalıdır (`app/server-ws.mjs` mevcut olduğunda varsayılan olarak öyledir).

#### Model kimliği: sade ChatGPT kimliğini kullanın (`codex/` öneki olmadan)

OpenAI **Codex CLI**, `supports_websockets = true` olduğunda model adını istemci tarafında
doğrular ve `codex/gpt-5.5` gibi **sağlayıcı önekli kimlikleri reddeder**
(`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). **Sade** kimliği gönderin (ör. `gpt-5.5`). OmniRoute'un köprüsü
yalnızca codex içindir; bu nedenle sade bir kimliği, üst hizmete tünellemeden önce
codex modeli olarak yeniden çözümler (`resolveCodexWsModelInfo`) — sade
`gpt-5.5` aksi takdirde HTTP üzerinden başka bir sağlayıcıya yönlendirilecek olsa bile.

#### OpenAI Codex CLI'ı yapılandırma

`~/.codex/config.toml` dosyasına WebSocket desteğine sahip özel bir sağlayıcı
ekleyerek Codex CLI'ı OmniRoute'a yönlendirin (mevcut bir yapılandırmaya dokunmamak
için ayrı bir `CODEX_HOME` kullanın):

```toml
model = "gpt-5.5"                 # sade kimlik — "codex/gpt-5.5" DEĞİL
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # sonunda eğik çizgi yok; WS URL'si türetilir (üretimde https/wss kullanın)
wire_api = "responses"                    # Şubat 2026'dan beri desteklenen tek değer
supports_websockets = true                # Responses-over-WS aktarımını etkinleştirir
env_key = "OMNIROUTE_API_KEY"             # OmniRoute API anahtarını içerir (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # bir OmniRoute API anahtarı (REQUIRE_API_KEY=false ise herhangi bir anahtar)
codex exec "Responda apenas: PONG"
```

CLI, `base_url + /responses` adresini bir WebSocket'e yükseltir ve OmniRoute bunu
seçilen codex OAuth bağlantısına tüneller. Yerel sunucuya karşı uçtan uca
doğrulanmıştır: ChatGPT, `codex.rate_limits` + `response.created` döndürür ve
tamamlamayı akış halinde iletir.

---

## Kota ve Sorun Bildirimi

| Yöntem | Yol                 | Açıklama                                                                                    |
| ------ | ------------------- | ------------------------------------------------------------------------------------------- |
| GET    | `/v1/quotas/check`  | Kayıtlı bir anahtar oluşturmadan önce `provider` + `accountId` kotasını önceden doğrular    |
| POST   | `/v1/issues/report` | Kota/anahtar oluşturma hatasını GitHub'a bildirir (`GITHUB_ISSUES_REPO` + token gerektirir) |

**Kimlik doğrulama:** Bearer API anahtarı (`isAuthenticated`).

---

## Self servis kullanımı (`/api/usage/om-usage`)

Herhangi bir API anahtarı **kendi** kullanımını ve kotalarını okuyabilir — yönetim kimlik doğrulaması gerekmez. Bu, bir
istemcinin (CLI, OmniCopilot paneli) anahtar sahibine harcamasını göstermek için kullandığı uç noktadır.

```bash
# Metin biçimi (geçmişten gelen sözleşme — terminal için düz metin)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Yapılandırılmış biçim — bir kullanıcı arayüzünün kullandığı biçim
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Anahtarda **`allowUsageCommand`** etkinleştirilmiş olmalıdır (varsayılan olarak kapalıdır — kontrol panelinin API anahtarı
yöneticisi bunu her anahtar için ayrı ayrı açıp kapatır). Bu özellik olmadan uç nokta `403` yanıtını verir.

`?format=json`, çağıranın bir ret yanıtından hiçbir zaman veri alanı okumaması için ayırt edilebilir bir yapı döndürür.
Başarı durumunda:

```jsonc
{
  "allowed": true,
  // yalnızca anahtar, anahtar başına kullanım limitlerini (günlük/haftalık USD) etkinleştirdiyse bulunur:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // seçilen sağlayıcının kota anlık görüntüsü veya henüz önbelleğe alınmış bir şey yoksa null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // kullanıcı arayüzünün birden fazla sağlayıcıyı yan yana işleyebilmesi için her bağlantının anlık görüntüsü:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

Ret durumunda (`401` geçersiz anahtar / `403` izin verilmedi) aynı rota
`{ "allowed": false, "error": { "message": "…" } }` döndürür — mevcut ancak boş bir `personal`/`provider`
(anahtara izin verilmiş, ancak henüz veri edinilmemiş) ret durumundan farklıdır ve yalnızca JSON biçimi
bunları birbirinden ayırır.

**Kimlik doğrulama:** çağıranın kendi Bearer API anahtarı, `isValidApiKey` ile doğrulanır — bu, `requireManagementAuth`
arkasında kalmaya devam eden yönetim yüzeyi (`/api/keys/…`) _değildir_.

### Ham ve Kesme Noktasına Göre Ayarlanmış Kota Yüzdeleri

Çağıranlar, `/api/usage/om-usage` kullanırken **düz metin çıktısında** ve yapılandırılmış **JSON çıktısında**
sunulan yüzdeler arasındaki ayrıma dikkat etmelidir:

| Unsur                 | Düz metin biçimi (`/api/usage/om-usage` / `@@om-usage`)                                                | JSON biçimi (`?format=json`)                                                                  |
| :-------------------- | :----------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------- |
| **Çıktı alanı**       | `NN% left` (ör. `20% left`)                                                                            | `provider.quotas` / `providers[].quotas`                                                      |
| **Ölçüm**             | **Kesme noktasına göre ayarlanmış kullanılabilir miktar**: kesme eşiğinin üzerindeki kalan kapasite    | **Ham üst sağlayıcı kotası**: sağlayıcının ayarlanmamış ölçümü                                |
| **Kesme ölçeklemesi** | Korunan rezervin `0% left` olarak görünmesi için `effectiveRemainingPercent()` aracılığıyla ölçeklenir | Yok (sağlayıcı tarafından bildirildiği şekliyle ham anlık görüntü değerleri)                  |
| **Eşik verileri**     | Görüntülenen yüzdeye dahil edilir                                                                      | Bağlantı başına `quotaWindowThresholds` içinde (veya sunucu varsayılanlarında) saklanır       |
| **Birincil tüketici** | Etkileşimli CLI'lar, terminal istemleri, insan operatörler                                             | Programatik entegrasyonlar, kontrol panelleri, analiz sistemleri, faturalandırma izleyicileri |

#### Kesme Noktası Ayarlama Formülü

OmniRoute, üst sağlayıcı kotalarının tükenmesini önlemek için proaktif kota kesme noktalarını destekler (bağlantı
`quotaWindowThresholds`, sağlayıcı varsayılanları veya genel dayanıklılık ayarları aracılığıyla yapılandırılır). Bir kota penceresinde
bir kesme eşiği (ör. `cutoff = 25%`) etkin olduğunda metin işleyici kalan miktarı şu şekilde hesaplar:

- `remaining <= cutoff` ise: `0%` döndürür.
- `remaining > cutoff` ise: `((remaining - cutoff) / (100 - cutoff)) * 100` döndürür.

Biçimlendirilmiş metin çıktısı bunu en yakın tam sayıya yuvarlar (`Math.round(...)`).

#### Açıklayıcı Örnek

**%60 ham kullanıma** (dolayısıyla **%40 ham kalan kotaya**) ve yapılandırılmış
**%25 kalan kota kesme** eşiğine sahip bir sağlayıcı penceresini ele alalım:

| Gösterim                      | Hesaplama                                          |  Kalan  |             Dolaylı Kullanım             |
| :---------------------------- | :------------------------------------------------- | :-----: | :--------------------------------------: |
| **Ham JSON (`?format=json`)** | Üst sağlayıcı anlık görüntüsü (`quotas[window]`)   | **%40** |                 **%60**                  |
| **Metin biçimi (`NN% left`)** | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **%20** | **%80** (`100 - remaining` hesaplanırsa) |

- **Metin neden %20 kaldığını gösterir:** Hesapta fiziksel olarak kalan %40 kotanın %25'i kesme politikası tarafından
  rezerve edilir. Yönlendirici bu bağlantıya yönlendirmeyi durdurmadan önce çağıranın kullanılabilir %75'lik payın yalnızca
  %15'i kadar kapasitesi kalmıştır. Ölçekleme, yönlendirmenin duracağı anda bağlantının tam olarak tükenme sinyali
  (`0% left`) vermesini sağlar.
- **JSON neden ham değerleri korur:** JSON yükü, harici araçların gerçek üst sağlayıcı kullanımına ve bağlantı düzeyindeki
  `quotaWindowThresholds` değerlerine sunucu tarafında kayıplı ölçekleme olmadan erişebilmesi için sağlayıcının tam anlık
  görüntüsünü (`UsageSnapshot`) döndürür.

#### Tüketici Geçiş Rehberi

Harici bir entegrasyon (örneğin bir düzenleyici eklentisi veya ajan uzantısı) daha önce metin
uç noktasını (`NN% left`) ayrıştırıyor ve kullanılan yüzdeyi `100 - NN` olarak hesaplıyorsa `?format=json` biçimine geçiş şu anlama gelir:

- Ham JSON değerlerini okumak, **gerçek üst sağlayıcı tüketimini** yansıtır (yukarıdaki örnekte %60 kullanılmıştır).
- Entegrasyon, metin uç noktasının kullanılabilir miktar semantiğini korumak isterse bağlantı düzeyindeki geçersiz kılmalar için
  `quotaWindowThresholds` kullanarak etkili kalan miktar formülünü istemci tarafında değerlendirebilir.

---

## Semantik Önbellek

```bash
# Önbellek istatistiklerini al
GET /api/cache/stats

# Tüm önbellekleri temizle
DELETE /api/cache/stats
```

Yanıt örneği:

```json
{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}
```

### Gecikme etkisi

Bir semantik önbellek İSABETİ, yanıtı **üst sağlayıcı çağrısı yapmadan** önbellekten sunar; bu nedenle bildirilen `X-OmniRoute-Response-Latency`, orijinal üst sağlayıcı gecikmesinden bağımsız olarak sıfıra yakındır. Gecikmeye duyarlı istemciler (performans karşılaştırması, p50/p99 izleme) `X-OmniRoute-Cache-Latency` yanıt başlığını kontrol etmelidir:

| Değer       | Anlamı                                                               |
| ----------- | -------------------------------------------------------------------- |
| `synthetic` | Yanıt önbellekten sunuldu; gecikme gerçek üst sağlayıcı süresi değil |
| _(yok)_     | Yanıt gerçek üst sağlayıcı çağrısından geldi                         |

### Anahtar başına önbelleği atlama

API anahtarları, `cacheDefaultMode` aracılığıyla semantik önbellek okumalarını devre dışı bırakabilir:

| Değer    | Davranış                                                          |
| -------- | ----------------------------------------------------------------- |
| `legacy` | Normal önbellek davranışı (varsayılan)                            |
| `bypass` | Önbellek aramasını tamamen atla; her zaman üst sağlayıcıya başvur |

Anahtar oluşturulurken (`POST /api/keys`) ayarlayın veya (`PATCH /api/keys/[id]`) güncelleyin:

```json
{ "cacheDefaultMode": "bypass" }
```

### İstek başına atlama

Herhangi bir istek, anahtar ayarlarından bağımsız olarak önbelleği atlayabilir:

```
X-OmniRoute-No-Cache: true
```

---

## Kontrol Paneli ve Yönetim

Yönetim rotaları (`/api/*`, herkese açık auth/login hariç) sıradan çıkarım API
anahtarlarıyla **yetkilendirilmez**. Kimlik bilgisi aileleri, kapsamlar ve curl
örnekleri: [Yönetim Kimlik Doğrulaması](../guides/MANAGEMENT-AUTH.md).

### Kimlik Doğrulama

| Uç Nokta                      | Yöntem   | Açıklama                                                                                                                                                                                                                                                                                                                   |
| ----------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/auth/login`             | POST     | Giriş                                                                                                                                                                                                                                                                                                                      |
| `/api/auth/logout`            | POST     | Çıkış                                                                                                                                                                                                                                                                                                                      |
| `/api/settings/require-login` | GET/POST | Giriş durumu (GET, herkese açık). POST parolayı ayarlar / girişi açıp kapatır: parola mevcut olduğunda yalnızca operatöre özeldir (kontrol paneli oturumu, yerel CLI veya giriş devre dışı — API anahtarları ve `oma_` token'ları `403` alır); kontrol paneli oturumu parolayı değiştirmek için `currentPassword` gönderir |

### Sağlayıcı Yönetimi

| Uç Nokta                                | Yöntem                    | Açıklama                                                                                                                                               |
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/providers`                        | GET/POST                  | Sağlayıcıları listele / oluştur                                                                                                                        |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | Bir sağlayıcıyı yönet                                                                                                                                  |
| `/api/providers/[id]/test`              | POST                      | Sağlayıcı bağlantısını test et                                                                                                                         |
| `/api/providers/[id]/models`            | GET                       | Sağlayıcı modellerini listele                                                                                                                          |
| `/api/providers/validate`               | POST                      | Sağlayıcı yapılandırmasını doğrula                                                                                                                     |
| `/api/providers/bulk`                   | POST                      | TEK bir sağlayıcı için toplu API anahtarı ekle                                                                                                         |
| `/api/providers/import`                 | POST                      | Ayrıştırılmış bir CSV/JSON dosyasından heterojen bir sağlayıcı LİSTESİ içe aktar (#6836); satır başına kısmi hata sonuçları                            |
| `/api/provider-nodes*`                  | Various                   | Sağlayıcı düğümü yönetimi                                                                                                                              |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | Özel modeller ve model bazında geçersiz kılmalar (ekle, güncelle, gizle/göster, sil)                                                                   |
| `/api/provider-models/validate-and-add` | POST                      | Yönetim kimlik doğrulamalı, isteğe bağlı katı bağlantı doğrulaması ve atomik özel model kaydı; bkz. [Model doğrulaması](../guides/MODEL-VALIDATION.md) |

Senkronize edilmiş/içe aktarılmış modeller için `PUT /api/provider-models`; `provider`,
`modelId` ve `maxOutputTokenOverride` parametrelerini kabul eder: pozitif bir tam sayı
manuel çıktı token sınırını ayarlar, `null` ise bunu temizleyerek varsayılanı geri yükler.
`GET /api/provider-models?provider=<provider>` bu değerleri `modelOutputOverrides` içinde
döndürür; buna özel model satırı olmayan modeller de dahildir. Geçersiz kılma, çalışma
zamanındaki `max_output_tokens` yeteneğini kullanır ve model yeniden senkronizasyonunda
korunur. OpenAI uyumlu sağlayıcı sayfası aynı düzenleme/temizleme kontrollerini sunar ve
açık görme (vision) desteğine sahip modelleri işaretler.

Özel Chat Completions düğümleri, açık akıl yürütme (reasoning) devre dışı bırakma
tercihlerini yukarı akış arka ucuna uyarlar. Başarılı bir bağlantı testi, `/models`
girdisinde tanınan bir `owned_by` değeri (`vllm`, `sglang` veya `llamacpp`) kanıtlanan her
tam model kimliği için sohbet şablonu kontrollerini otomatik olarak seçer. Şeffaf OpenAI
uyumlu sarmalayıcılar, orijinal model girdisini iç içe geçmiş bir `openai` nesnesi içinde
koruyabilir; algılama bu tür en fazla üç zarfı izler. Sahiplik bilgisi eksik, bilinmeyen
veya çelişkili olan modeller olağan OpenAI davranışını korur. Algılama mevcut katalog
isteğini yeniden kullanır, tamamlama token'ı üretmez ve bağlantı uç noktası değiştiğinde
geçersiz kılınır.

Bu meta verileri sunmayan bir arka uçta davranışı sabitlemek için mevcut kısmi sağlayıcı
güncelleme API'sini kullanın:

```json
{
  "providerSpecificData": {
    "reasoningControl": "chat-template"
  }
}
```

Bu gövdeyi `PUT /api/providers/<connection-id>` ile gönderin. Bu bağlantıda, `none` olarak
belirtilen açık bir akıl yürütme çabası, `chat_template_kwargs.thinking=false` ve
`chat_template_kwargs.enable_thinking=false` olarak gönderilir. Sunucu tarafı bir akıl yürütme
kuralı bir çabayı zorlamadığı sürece açık yerel şablon değerleri geçerliliğini korur. Bu ayar
yalnızca özel bir OpenAI uyumlu bağlantı bir Chat Completions gövdesi gönderdiğinde uygulanır;
Responses istekleri ve sıradan sağlayıcılar yerel istek biçimlerini korur. Sıradan OpenAI
`reasoning_effort` doğrudan geçişini zorlamak için `reasoningControl` değerini `openai` olarak
ayarlayın veya otomatik algılamayı kullanmak için boş bırakın/`null` olarak ayarlayın.

Claude Code otomatik mod sınıflandırıcı istekleri, açık akıl yürütme kontrolleri
içermediğinde yerel thinking'i varsayılan olarak devre dışı bırakır. Algılama, model adlarını
veya tamamlama sınırlarını değil, Claude formatındaki isteklerde sınıflandırıcının sistem
işaretini kullanır. Açık gövde kontrolleri, desteklenen effort/thinking başlıkları, yönlendirme
kuralları ve çözümlenmiş model çabası mevcut önceliklerini korur. Her iki sınıflandırıcı aşaması
da istemlerini, tamamlama sınırlarını, durdurma dizilerini ve gerçek yukarı akış izin kararlarını
korur; ikinci aşama, istenen görünür akıl yürütmeyi hâlâ sıradan metin olarak üretebilir.

### OAuth Akışları

| Uç Nokta                         | Metot   | Açıklama               |
| -------------------------------- | ------- | ---------------------- |
| `/api/oauth/[provider]/[action]` | Çeşitli | Sağlayıcıya özel OAuth |

### Yönlendirme ve Yapılandırma

| Uç Nokta              | Metot    | Açıklama                           |
| --------------------- | -------- | ---------------------------------- |
| `/api/models/alias`   | GET/POST | Model takma adları                 |
| `/api/models/catalog` | GET      | Sağlayıcı + türe göre tüm modeller |
| `/api/combos*`        | Çeşitli  | Combo yönetimi                     |
| `/api/keys*`          | Çeşitli  | API anahtarı yönetimi              |
| `/api/pricing`        | GET      | Model fiyatlandırması              |

### Kullanım ve Analitik

| Uç Nokta                         | Metot           | Açıklama                                                                                                                                                                                                                                                                                                        |
| -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | Kullanım geçmişi                                                                                                                                                                                                                                                                                                |
| `/api/usage/logs`                | GET             | Kullanım günlükleri                                                                                                                                                                                                                                                                                             |
| `/api/usage/request-logs`        | GET             | İstek düzeyi günlükleri                                                                                                                                                                                                                                                                                         |
| `/api/usage/[connectionId]`      | GET             | Bağlantı başına kullanım                                                                                                                                                                                                                                                                                        |
| `/api/usage/token-limits`        | GET/POST/DELETE | API anahtarı başına token sınırı bütçeleri                                                                                                                                                                                                                                                                      |
| `/api/usage/model-latency-stats` | GET             | Sağlayıcı/model başına kayan gecikme toplamı (avg/p50/p95/p99, başarı oranı); filtreler: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                        |
| `/api/usage/cache-health`        | GET             | `call_logs` üzerinde prompt-cache sağlık özeti — yazma/okuma oranı, p50/p90/p99 yazma boyutu dağılımı, yoğun yazma yoğunlaşması, model başına ayrım ve `healthy`/`degraded`/`thrash`/`no-data` kararı; sorgu parametreleri `range` (`1h`\|`24h`\|`7d`\|`30d`, varsayılan `24h`) ve isteğe bağlı `model` (#8827) |

### API anahtarı izinleri

`PATCH /api/keys/{id}` mevcut bir anahtarın izinlerini günceller. Her `/api/keys*` rotası gibi, bir inference anahtarı değil, yönetim yetkilendirmesi gerektirir (bkz. [Yönetim Kimlik Doğrulaması](../guides/MANAGEMENT-AUTH.md)). Yalnızca değiştirmek istediğiniz alanları gönderin; bunların hiçbirini içermeyen bir istek `No valid fields to update` hatasıyla reddedilir. Kabul edilen alanlar, `src/shared/validation/schemas/keys.ts` dosyasındaki `updateKeyPermissionsSchema` tarafından tanımlanır.

| Alan                                        | Tür                                                                       | Notlar                                                                                                                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | string, 1-200 karakter                                                    |                                                                                                                                                                                   |
| `isActive`                                  | boolean                                                                   |                                                                                                                                                                                   |
| `isBanned`                                  | boolean                                                                   |                                                                                                                                                                                   |
| `expiresAt`                                 | ISO 8601 datetime veya `null`                                             | `null` süre sonunu temizler                                                                                                                                                       |
| `modelAccessMode`                           | `all` \| `restricted`                                                     | Mod `all` olduğunda `allowedModels` boş olmalıdır                                                                                                                                 |
| `allowedModels`, `blockedModels`            | string dizisi, en fazla 1000                                              |                                                                                                                                                                                   |
| `allowedCombos`                             | string dizisi, en fazla 500                                               | Anahtarın hangi kombinasyonları çağırabileceğini denetler; doğrudan modeller `modelAccessMode` / `allowedModels` tarafından yönetilir                                             |
| `connectionAccessMode`                      | `all` \| `restricted`                                                     | `restricted` olduğunda `allowedConnections` boş olamaz, `all` olduğunda boş olmalıdır                                                                                             |
| `allowedConnections`                        | UUID dizisi, en fazla 100                                                 |                                                                                                                                                                                   |
| `allowAutoCombos`                           | boolean                                                                   | `false` bu anahtarla `auto/*` modellerine yapılan istekleri reddeder; bunu hiç ayarlamamış anahtarlara izin verilir                                                               |
| `catalogScope`                              | `all` \| `combos` \| `models`                                             | Bu anahtar için `GET /v1/models` isteğinin ne listeleyeceğini belirler (yalnızca kombinasyonlar, yalnızca modeller veya her ikisi); anahtarın neleri çağırabileceğini değiştirmez |
| `forcedModel`                               | en fazla 300 karakterlik string veya `null`                               | Sohbet isteklerini `X-Route-Model` ve `body.model` yerine bu modele/kombinasyona yönlendirir; anahtarın limitleri yine de geçerlidir                                              |
| `noLog`, `autoResolve`                      | boolean                                                                   |                                                                                                                                                                                   |
| `throttleDelayMs`                           | integer, 0-300000                                                         |                                                                                                                                                                                   |
| `maxSessions`                               | integer, 0-10000                                                          |                                                                                                                                                                                   |
| `rateLimits`                                | `{ limit, window }` dizisi (pozitif tam sayılar, en fazla 50) veya `null` | `null` limitleri temizler                                                                                                                                                         |
| `accessSchedule`                            | zamanlama nesnesi veya `null`                                             | `null` zamanlamayı temizler                                                                                                                                                       |
| `scopes`                                    | string dizisi, en fazla 32                                                |                                                                                                                                                                                   |
| `allowedEndpoints`                          | string dizisi, en fazla 20                                                |                                                                                                                                                                                   |
| `streamDefaultMode`                         | `legacy` \| `json`                                                        |                                                                                                                                                                                   |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                                      | Bkz. [Anahtar bazlı önbellek atlama](#per-key-cache-bypass)                                                                                                                       |
| `compressionEnabled`                        | boolean                                                                   |                                                                                                                                                                                   |
| `codexServiceMode`                          | Codex servis modlarından biri                                             |                                                                                                                                                                                   |
| `disableNonPublicModels`                    | boolean                                                                   |                                                                                                                                                                                   |
| `allowUsageCommand`                         | boolean                                                                   |                                                                                                                                                                                   |
| `usageLimitEnabled`                         | boolean                                                                   |                                                                                                                                                                                   |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 veya `null`                                                   |                                                                                                                                                                                   |
| `chaosModeEnabled`                          | boolean                                                                   |                                                                                                                                                                                   |

```bash
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
```

### Ayarlar

| Endpoint                              | Metot         | Açıklama                                                                                                                                                                                                                                                                                             |
| ------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/settings`                       | GET/PUT/PATCH | Genel ayarlar. Güvenlik politikası anahtarları (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) `currentPassword` ve bir operatör kimlik bilgisi gerektirir — API anahtarları ve `oma_` tokenları `403` alır; her mutasyon `admin` erişim tokenı kapsamını gerektirir |
| `/api/settings/proxy`                 | GET/PUT       | Ağ proxy yapılandırması                                                                                                                                                                                                                                                                              |
| `/api/settings/proxy/test`            | POST          | Proxy bağlantısını test et                                                                                                                                                                                                                                                                           |
| `/api/settings/ip-filter`             | GET/PUT       | IP izin listesi/engelleme listesi                                                                                                                                                                                                                                                                    |
| `/api/settings/thinking-budget`       | GET/PUT       | Thinking/reasoning **isteği** yeniden yazma modu (passthrough / auto-strip / custom / adaptive). Sıkıştırmadan bağımsızdır. Bkz. [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md).                                                                                                                 |
| `/api/settings/system-prompt`         | GET/PUT       | Genel sistem istemi                                                                                                                                                                                                                                                                                  |
| `/api/settings/compression`           | GET/PUT       | Genel sıkıştırma yapılandırması                                                                                                                                                                                                                                                                      |
| `/api/settings/purge-request-history` | POST          | İstek günlüğü satırlarını ve yerel çağrı günlüğü artifaktlarını temizle                                                                                                                                                                                                                              |

### Bağlam ve Sıkıştırma

| Uç Nokta                               | Yöntem         | Açıklama                                                             |
| -------------------------------------- | -------------- | -------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | off/lite/standard/aggressive/ultra/RTK/stacked sıkıştırma önizlemesi |
| `/api/compression/language-packs`      | GET            | Mevcut Caveman dil paketlerini listele                               |
| `/api/compression/rules`               | GET            | Caveman kural meta verilerini listele                                |
| `/api/context/caveman/config`          | GET/PUT        | Caveman'a özgü ayarlar takma adı                                     |
| `/api/context/rtk/config`              | GET/PUT        | Özel filtreler ve ham çıktı saklama dahil RTK'ye özgü ayarlar        |
| `/api/context/rtk/filters`             | GET            | RTK filtre kataloğu ve özel filtre tanılamaları                      |
| `/api/context/rtk/test`                | POST           | Bir metin yüküne karşı RTK önizleme/testi çalıştır                   |
| `/api/context/rtk/raw-output/[id]`     | GET            | Saklanan sansürlenmiş ham çıktıyı işaretçi kimliğine göre oku        |
| `/api/context/combos`                  | GET/POST       | Sıkıştırma kombinasyonu listele/oluştur                              |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Sıkıştırma kombinasyonu detay/güncelle/sil                           |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Sıkıştırma kombinasyonlarını yönlendirme kombinasyonlarına ata       |
| `/api/context/analytics`               | GET            | Sıkıştırma analitiği takma adı                                       |

### İzleme

| Uç Nokta                             | Yöntem     | Açıklama                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Aktif oturum takibi                                                                                                                                                                                                                                                                                                                                                                                            |
| `/api/rate-limits`                   | GET        | Hesap başına hız sınırları                                                                                                                                                                                                                                                                                                                                                                                     |
| `/api/monitoring/health`             | GET        | Sağlık kontrolü + sağlayıcı özeti (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Yönetim görünümü `credentialHealth` içerir: probe-cache skalerleri, `failed>0` olduğunda `failedConnections` ve `staleDbNonOkCount` (SQLite yapışkan `test_status` değeri, gösterge değil). Bkz. [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | Önbellek istatistikleri / temizleme                                                                                                                                                                                                                                                                                                                                                                            |
| `/api/modality-bridge/stats`         | GET        | Bellek içi `attempts`, başarılar/`bridged`, başarısızlıklar, önbellek isabetleri, `totalLatencyMs`, `latencySamples`, örnek sayısına bölünmüş `averageLatencyMs` ve son kullanım zamanı (yeniden başlatmada sıfırlanır; yönetim kimlik doğrulaması)                                                                                                                                                            |
| `/api/modality-bridge/video/runtime` | GET        | Yönetim kimlik doğrulaması/yoklamasından önce katı güvenilir geri döngü (loopback) kontrolü; temizlenmiş FFmpeg/ffprobe kullanılabilirliği ve sürümleri (no-store)                                                                                                                                                                                                                                             |
| `/api/modality-bridge/video/extract` | POST       | Dahili kimliği doğrulanmış güvenilir geri döngü bayt aracısı; 50 MiB giriş, sınırlı kuyruk/32 MiB çıkış, `503` kapasite, `499` bağlantı kesilmesi, `504` zaman aşımı; herkese açık bir yükleme API'si değildir                                                                                                                                                                                                 |

### Yedekleme & Dışa/İçe Aktarma

| Uç Nokta                    | Yöntem | Açıklama                                                                               |
| --------------------------- | ------ | -------------------------------------------------------------------------------------- |
| `/api/db-backups`           | GET    | Mevcut yedekleri listele                                                               |
| `/api/db-backups`           | PUT    | Manuel yedek oluştur                                                                   |
| `/api/db-backups`           | POST   | Belirli bir yedekten geri yükle                                                        |
| `/api/db-backups`           | PATCH  | Yedek saklama ayarlarını kaydet (yalnızca operatör)                                    |
| `/api/db-backups`           | DELETE | Saklanan yedekleri saklama ayarlarına göre temizle (yalnızca operatör)                 |
| `/api/db-backups/export`    | GET    | Veritabanını .sqlite dosyası olarak indir                                              |
| `/api/db-backups/import`    | POST   | Veritabanını değiştirmek için .sqlite dosyası yükle (`?dryRun=true` yalnızca doğrular) |
| `/api/db-backups/exportAll` | GET    | Tam yedeği .tar.gz arşivi olarak indir                                                 |

`/api/db-backups/export`, `/api/db-backups/exportAll` ve `/api/settings/export-json` saklanan tüm kimlik bilgilerini verir; bu nedenle pano oturumu ya da yerel CLI (veya oturum açmanın devre dışı olması) gerektirirler. Herhangi bir kapsamdaki API anahtarları ve `oma_` erişim belirteçleri `403` alır. Geri yüklemeler de aynı sınırı korur: `POST /api/db-backups/import` (`dryRun=true` dahil), `POST /api/db-backups` (id ile geri yükleme) ve `POST /api/settings/import-json` canlı veritabanını veya ayarları değiştirir; bu nedenle bir makine kimlik bilgisi de orada `403` alır; `omniroute sync import` yerel CLI kimlik bilgisini gönderir. Aynı durum `DELETE /api/db-backups` (saklanan yedekleri temizleme) ve `PATCH /api/db-backups` (saklama ayarları: kalıcı değerler her yedeklemeden sonraki otomatik temizlemeyi yönetir) için de geçerlidir. Listeleme (`GET`) ve manuel yedek oluşturma (`PUT`) normal yönetim kimlik doğrulamasını korur.

### Bulut Senkronizasyonu

| Uç Nokta               | Yöntem  | Açıklama                       |
| ---------------------- | ------- | ------------------------------ |
| `/api/sync/cloud`      | Various | Bulut senkronizasyon işlemleri |
| `/api/sync/initialize` | POST    | Senkronizasyonu başlat         |
| `/api/cloud/*`         | Various | Bulut yönetimi                 |

### Tüneller

| Uç Nokta                   | Yöntem | Açıklama                                                                              |
| -------------------------- | ------ | ------------------------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET    | Pano için Cloudflare Quick Tunnel kurulum/çalışma durumunu oku                        |
| `/api/tunnels/cloudflared` | POST   | Cloudflare Quick Tunnel'ı etkinleştir veya devre dışı bırak (`action=enable/disable`) |
| `/api/tunnels/ngrok`       | GET    | Pano için ngrok Tunnel çalışma durumunu oku                                           |
| `/api/tunnels/ngrok`       | POST   | ngrok Tunnel'ı etkinleştir veya devre dışı bırak (`action=enable/disable`)            |

### CLI Araçları

| Uç Nokta                           | Yöntem | Açıklama                 |
| ---------------------------------- | ------ | ------------------------ |
| `/api/cli-tools/claude-settings`   | GET    | Claude CLI durumu        |
| `/api/cli-tools/codex-settings`    | GET    | Codex CLI durumu         |
| `/api/cli-tools/droid-settings`    | GET    | Droid CLI durumu         |
| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI durumu      |
| `/api/cli-tools/runtime/[toolId]`  | GET    | Genel CLI çalışma zamanı |

CLI yanıtları şunları içerir: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### ACP Aracıları

| Uç Nokta          | Yöntem | Açıklama                                                                |
| ----------------- | ------ | ----------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Algılanan tüm aracıları (yerleşik + özel) durumlarıyla birlikte listele |
| `/api/acp/agents` | POST   | Özel aracı ekle veya algılama önbelleğini yenile                        |
| `/api/acp/agents` | DELETE | `id` sorgu parametresiyle özel bir aracıyı kaldır                       |

GET yanıtı `agents[]` (id, name, binary, version, installed, protocol, isCustom) ve `summary` (total, installed, notFound, builtIn, custom) içerir.

### Dayanıklılık ve Hız Sınırları

| Uç Nokta                          | Yöntem    | Açıklama                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | İstek kuyruğu, bağlantı soğuma süresi, sağlayıcı kesicisi ve bekleme ayarlarını al/güncelle                                                                                                                                                                                                                                                                                                                                                       |
| `/api/resilience/reset`           | POST      | Sağlayıcı devre kesicilerini sıfırla                                                                                                                                                                                                                                                                                                                                                                                                              |
| `/api/resilience/model-cooldowns` | GET       | Etkin (sağlayıcı, bağlantı, model) bazlı kilitlenmeleri kalan süreye göre sıralanmış olarak listele                                                                                                                                                                                                                                                                                                                                               |
| `/api/resilience/model-cooldowns` | DELETE    | Bir model kilitlenmesini temizle — her şeyi silmek için gövdede `{provider, model}` veya `{all: true}` gönder                                                                                                                                                                                                                                                                                                                                     |
| `/api/rate-limits`                | GET/POST  | Hesap bazında hız sınırı durumu (GET) veya bir bağlantı için hız sınırı korumasını aç/kapat (POST `{connectionId, enabled}`). `rateLimitProtection` için desteklenen yazma yoludur (asla `PUT /api/providers/[id]` üzerinden değiştirilmez). Not: `enabled: false` açık korumayı devre dışı bırakır ancak etkin bir API anahtarı bağlantısını genel otomatik etkinleştirme güvenlik ağının (`autoEnableApiKeyProviders`) kapsamı dışına çıkarmaz. |
| `/api/rate-limit`                 | GET       | Genel hız sınırı yapılandırması (kullanımdan kaldırıldı; `/api/rate-limits` takma adı)                                                                                                                                                                                                                                                                                                                                                            |

> Dört `/api/resilience/*` rotasının tümü **yönetim kimlik doğrulaması** gerektirir (`requireManagementAuth`). Sağlayıcı kesicisi, bağlantı soğuma süresi ve model kilitlenmesi arasındaki farkların tam dökümü için [Dayanıklılık (genişletilmiş)](#resilience-extended) bölümüne bakın.

### Evals

| Uç Nokta     | Yöntem   | Açıklama                                                   |
| ------------ | -------- | ---------------------------------------------------------- |
| `/api/evals` | GET/POST | Değerlendirme paketlerini listele / değerlendirme çalıştır |

### Politikalar

| Uç Nokta        | Yöntem          | Açıklama                         |
| --------------- | --------------- | -------------------------------- |
| `/api/policies` | GET/POST/DELETE | Yönlendirme politikalarını yönet |

### Uyumluluk

| Uç Nokta                    | Yöntem | Açıklama                                |
| --------------------------- | ------ | --------------------------------------- |
| `/api/compliance/audit-log` | GET    | Uyumluluk denetim günlüğü (son N kayıt) |

### v1beta (Gemini Uyumlu)

| Uç Nokta                   | Yöntem | Açıklama                            |
| -------------------------- | ------ | ----------------------------------- |
| `/v1beta/models`           | GET    | Modelleri Gemini formatında listele |
| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` uç noktası |

Bu uç noktalar, yerel Gemini SDK uyumluluğu bekleyen istemciler için Gemini'nin API formatını yansıtır.

### Dahili / Sistem API'leri

| Uç Nokta                 | Yöntem | Açıklama                                                     |
| ------------------------ | ------ | ------------------------------------------------------------ |
| `/api/init`              | GET    | Uygulama başlatma kontrolü (ilk çalıştırmada kullanılır)     |
| `/api/tags`              | GET    | Ollama uyumlu model etiketleri (Ollama istemcileri için)     |
| `/api/restart`           | POST   | Sunucunun sorunsuz yeniden başlatılmasını tetikle            |
| `/api/shutdown`          | POST   | Sunucunun sorunsuz kapatılmasını tetikle                     |
| `/api/system/env/repair` | POST   | OAuth sağlayıcı ortam değişkenlerini onar                    |
| `/api/system/version`    | GET    | Mevcut/en son sürüm, güncelleme durumu, yayın kanalı         |
| `/api/system/version`    | POST   | En son sürüme dağıtım ortamına duyarlı bir güncelleme başlat |

> **Not:** Bu uç noktalar sistem tarafından dahili olarak veya Ollama istemci uyumluluğu için kullanılır. Son kullanıcılar tarafından genellikle çağrılmazlar.

### OAuth Ortam Onarımı _(v3.6.1+)_

```bash
POST /api/system/env/repair
Content-Type: application/json

{
  "provider": "claude-code"
}
```

Belirli bir sağlayıcı için eksik veya bozuk OAuth ortam değişkenlerini onarır. Döndürür:

```json
{
  "success": true,
  "repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
  "backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
```

### Sürüm ve Yayın Kanalı

```bash
GET /api/system/version
```

Yalnızca loopback üzerinden erişilebilen yönetim rotası (admin auth). Çalışan sürümü,
yayımlanmış en son sürümü ve otomatik güncelleme durumunu döndürür. `releaseChannel` ve
`channels` ek (additive) alanlardır (rail 3.8.54); `channel` anlamını korur — pano
güncelleyicisinin kullandığı dağıtım modu (`npm`, `source` veya `docker-compose`).

```json
{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
```

- `releaseChannel` — çalışan derlemenin npm kanalı: `-nightly.*` sürümleri için `nightly`,
  diğer ön sürümler (`-rc.*`, `-beta.*`, `-alpha.*`) için `next`, `channels.latest` değerinden
  daha eski bir ana sürüme ait kararlı sürüm için `lts`, aksi halde `latest`. Yayınlama
  anında npm dist-tag'ini seçen `scripts/release/dist-tag.mjs` ile aynı kurallar geçerlidir.
- `channels` — her dist-tag'in yayımlanmış baş (head) sürümü; `npm view omniroute dist-tags`
  üzerinden alınır (registry HTTP yedeğiyle) ve `latest` ile aynı 10 dakikalık TTL ile
  önbelleğe alınır. `latest` her zaman mevcuttur (önce `latest` alanına, ardından
  `"unavailable"` değerine geri düşer); `next`, `nightly` ve `lts` yalnızca ilgili dist-tag
  mevcut olduğunda görünür. `Cache-Control: no-cache` içeren bir istek her iki sorguyu da
  yeniler.

Kanal modeli (`latest` = 4.0 GA'ya kadar v3, `next` = rc, `nightly` = `develop`
derlemeleri, `lts` = 4.0 GA sonrası v3 yamaları) `docs/ops/RELEASE_STRATEGY.md`
dosyasında açıklanmıştır.

---

## Ses Transkripsiyonu

```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```

Yapılandırılmış herhangi bir STT sağlayıcısını kullanarak ses dosyalarını yazıya dökün. İlk yol
segmenti yerel sağlayıcıyı seçer (`openai/…`, `deepgram/…`). Başka bir sağlayıcının
modelini yeniden dışa aktaran ağ geçitleri nitelikli bir kimlik kullanır
(`openrouter/deepgram/nova-3`).

**İstek:**

```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"
```

**Yanıt:**

```json
{
  "text": "Hello, this is the transcribed audio content.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**Örnek model kimlikleri:** `openai/whisper-1` (bir OpenAI anahtarı gerektirir),
`openrouter/deepgram/nova-3` (bir OpenRouter anahtarı gerektirir),
`deepgram/nova-3` (yerel bir Deepgram anahtarı gerektirir). Yalın bir
`deepgram/nova-3` isteği OpenRouter'ı **kullanmaz**.

**Desteklenen biçimler:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## Ollama Uyumluluğu

Ollama'nın API biçimini kullanan istemciler için:

```bash
# Sohbet uç noktası (Ollama biçimi)
POST /v1/api/chat

# Model listeleme (Ollama biçimi)
GET /api/tags
```

İstekler, Ollama ile dahili biçimler arasında otomatik olarak dönüştürülür.

## Token İçeren VS Code / Başlıksız Takma Adlar

Bir entegrasyon `Authorization` başlığı ekleyemediğinde ve API anahtarının temel URL'ye gömülmesi gerektiğinde bu takma adları kullanın.

```bash
# OpenAI tarzı katalog takma adı
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# OpenAI tarzı sohbet takma adları
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# Ollama tarzı takma adlar
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

Örnek:

```bash
curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'
```

Notlar:

- Token içeren takma adlar, `/v1/*` ve `/api/tags` ile aynı işleyicileri yeniden kullanır; yanıt yapıları aynı kalır.
- İstemci özel başlıkları desteklediğinde `Authorization: Bearer ...` kullanımını tercih edin.
- URL tabanlı token'lar ters proxy günlüklerinde, tarayıcı geçmişinde ve OmniRoute dışındaki telemetride görünebilir. Bunları varsayılan kimlik doğrulama modu olarak değil, bir uyumluluk seçeneği olarak değerlendirin.

---

## Telemetri

```bash
# Gecikme telemetrisi özetini al (sağlayıcı başına p50/p95/p99)
GET /api/telemetry/summary
```

**Yanıt:**

```json
{
  "providers": {
    "claudeCode": { "p50": 245, "p95": 890, "p99": 1200, "count": 150 },
    "github": { "p50": 180, "p95": 620, "p99": 950, "count": 320 }
  }
}
```

---

## Bütçe

```bash
# Tüm API anahtarlarının bütçe durumunu al
GET /api/usage/budget

# Bir bütçe belirle veya güncelle
POST /api/usage/budget
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "dailyLimitUsd": 5.00,
  "weeklyLimitUsd": 30.00,
  "monthlyLimitUsd": 100.00,
  "warningThreshold": 0.8,
  "resetInterval": "monthly"
}
```

> **Şema notları** (`setBudgetSchema`): `apiKeyId` zorunludur; `dailyLimitUsd`, `weeklyLimitUsd` veya `monthlyLimitUsd` alanlarından en az biri sıfırdan büyük olmalıdır. İsteğe bağlı alanlar: `warningThreshold` (0–1), `resetInterval` (`daily` | `weekly` | `monthly`), `resetTime` (`HH:MM`). Eski `{keyId, limit, period}` yapısı `400 Bad Request` döndürür.

## Token Sınırları

API anahtarı başına **token** bütçeleri (yukarıdaki USD tabanlı Bütçeden farklıdır). İstek yolunda doğrudan uygulanır: Bir anahtarın geçerli pencere kullanımı sınırına ulaştığında istekler `429 Too Many Requests` ile reddedilir. Sınırlar belirli bir `model` veya `provider` ile kapsamlandırılabilir ya da anahtar genelinde `global` olarak uygulanabilir; birden fazla sınır bir istekle eşleştiğinde en kısıtlayıcı olan geçerli olur.

```bash
# Bir anahtarın token sınırlarını listele (canlı pencere kullanımını içerir)
GET /api/usage/token-limits?apiKeyId=key-123

# Bir token sınırı oluştur veya güncelle
POST /api/usage/token-limits
Content-Type: application/json

{
  "apiKeyId": "key-123",
  "scopeType": "model",
  "scopeValue": "openai/gpt-4o",
  "tokenLimit": 1000000,
  "resetInterval": "monthly",
  "enabled": true
}

# Kimliğe göre bir token sınırını sil
DELETE /api/usage/token-limits?id=tl-abc
```

> **Şema notları** (`setTokenLimitSchema`): `apiKeyId` ve `scopeType` (`model` | `provider` | `global`) zorunludur. `scopeType`, `global` olmadığı sürece `scopeValue` zorunludur (ör. `model` kapsamı için bir model kimliği, `provider` kapsamı için bir sağlayıcı kimliği). `tokenLimit` pozitif bir tam sayı olmalıdır (dizeden dönüştürülür). İsteğe bağlı: `id` (oluşturmak için dahil etmeyin, güncellemek için belirtin), `resetInterval` (`daily` | `weekly` | `monthly`, varsayılan `monthly`), `resetTime` (`HH:MM`), `enabled` (varsayılan `true`). `GET` yanıtları her sınırı `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` ve `nextResetAt` ile zenginleştirir. Bu, yönetim sınıfı bir uç noktadır (kimlik doğrulama, authz işlem hattı tarafından merkezi olarak uygulanır).

## İstek İşleme

1. İstemci `/v1/*` adresine istek gönderir
2. Rota işleyicisi `handleChat`, `handleEmbedding`, `handleAudioTranscription` veya `handleImageGeneration` çağrısını yapar
3. Model çözümlenir (doğrudan sağlayıcı/model veya takma ad/kombinasyon)
4. Kimlik bilgileri, hesap kullanılabilirliği filtrelenerek yerel veritabanından seçilir
5. Sohbet için: `handleChatCore`, semantik/imza önbelleğini kontrol eder ve kombinasyon sıkıştırma ayarlarını çözümler
6. Etkinleştirildiğinde proaktif sıkıştırma, sağlayıcı çevirisinden önce çalışır (`lite`, Caveman, RTK veya yığınlanmış)
7. Sağlayıcı yürütücüsü yukarı akış isteğini gönderir
8. Yanıt, istemci biçimine geri çevrilir (sohbet) veya olduğu gibi döndürülür (gömme/görsel/ses)
9. Kullanım, sıkıştırma analizleri ve istek günlükleri kaydedilir
10. Hatalarda, kombinasyon kurallarına göre geri dönüş uygulanır

Tam mimari başvurusu: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Kombinasyon Yönetimi

Daha üst düzey yönlendirme kombinasyonları (daha önce `/api/combos*` altında özetlenmiştir), bir model kimliği deseninden bire bir eşlenerek OpenAI tarzı bir model kimliğinin şeffaf biçimde bir kombinasyona yönlendirilmesini de sağlayabilir.

| Yöntem | Yol                              | Açıklama                                                                        |
| ------ | -------------------------------- | ------------------------------------------------------------------------------- |
| GET    | `/api/model-combo-mappings`      | Tüm model→kombinasyon eşlemelerini listele                                      |
| POST   | `/api/model-combo-mappings`      | Eşleme oluştur — gövde: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | Tek bir eşlemeyi getir                                                          |
| PUT    | `/api/model-combo-mappings/[id]` | Mevcut bir eşlemenin alanlarını güncelle                                        |
| DELETE | `/api/model-combo-mappings/[id]` | Bir eşlemeyi kaldır                                                             |

**Kimlik doğrulama:** yönetim oturumu/API anahtarı (`requireManagementAuth`).

---

## Webhook'lar

OmniRoute olayları (istek tamamlanması, kotanın tükenmesi, anahtar rotasyonu vb.) için giden webhook abonelikleri.

| Yöntem | Yol                       | Açıklama                                                                  |
| ------ | ------------------------- | ------------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | Webhook'ları listele (gizli anahtarlar `<prefix>...` şeklinde maskelenir) |
| POST   | `/api/webhooks`           | Webhook oluştur — gövde: `{url, events?: ["*"], secret?, description?}`   |
| GET    | `/api/webhooks/[id]`      | Bir webhook'u getir                                                       |
| PUT    | `/api/webhooks/[id]`      | url/events/secret/description alanlarını güncelle                         |
| DELETE | `/api/webhooks/[id]`      | Bir webhook'u kaldır                                                      |
| POST   | `/api/webhooks/[id]/test` | Webhook URL'sine bir test yükü gönder ve teslimat durumunu döndür         |

**Kimlik doğrulama:** yönetim oturumu/API anahtarı (`requireManagementAuth`).

---

## Kayıtlı Anahtarlar (Otomatik Yönetim)

Otomatik anahtar yönetimi alt sistemi tarafından, günlük/saatlik kotalarla bir arka uç sağlayıcısı/hesabı üzerinden API anahtarları oluşturmak ve döndürmek için kullanılır.

| Yöntem | Yol                                   | Açıklama                                                                                                                                                                                                       |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Kayıtlı anahtarları listele (yalnızca maskelenmiş ön ek)                                                                                                                                                       |
| POST   | `/api/v1/registered-keys`             | Yeni bir kayıtlı anahtar oluştur — gövde: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Ham anahtarı **yalnızca bir kez** döndürür. Kota reddinde `429` döndürür. |
| GET    | `/api/v1/registered-keys/[id]`        | Kayıtlı bir anahtarın meta verilerini getir (ham anahtar materyali olmadan)                                                                                                                                    |
| DELETE | `/api/v1/registered-keys/[id]`        | Kayıtlı bir anahtarı iptal et                                                                                                                                                                                  |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Açık iptal uç noktası (DELETE ile aynı etki)                                                                                                                                                                   |

**Kimlik doğrulama:** yönetim oturumu/API anahtarı (`requireManagementAuth`) — `/api/keys` ile aynı koruma mekanizması: bir pano oturumu, yerel CLI belirteci veya `manage`/`admin` kapsamına sahip bir API anahtarı; yalnızca çıkarım amaçlı API anahtarları `403` alır. Ayrıca `/v1/quotas/check` ve `/v1/issues/report` bölümlerine bakın.

---

## Ajanlar Protokolü

OmniRoute kullanıcıları adına uzaktan yürütülen bulut ajanı görevleri (Claude Code, Codex Cloud, OpenHands vb.).

| Yöntem | Yol                           | Açıklama                                                                                                                                                   |
| ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | Görevleri listeler — isteğe bağlı `?provider=`, `?status=`, `?limit=` (1–500, varsayılan 50)                                                               |
| POST   | `/api/v1/agents/tasks`        | Görev oluşturur — gövde `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`) ile doğrulanır. Görev zarfıyla birlikte `201` döndürür |
| DELETE | `/api/v1/agents/tasks?id=...` | Bir görevi siler                                                                                                                                           |
| GET    | `/api/v1/agents/tasks/[id]`   | Görevi okur — bir `external_id` ayarlandığında durumu üst akış bulut ajanından eşzamanlı olarak yeniler                                                    |
| POST   | `/api/v1/agents/tasks/[id]`   | Ayrıştırılmış eylem: `{action: "approve"}`, `{action: "message", message}` veya `{action: "cancel"}`                                                       |
| DELETE | `/api/v1/agents/tasks/[id]`   | Belirli bir görevi kimliğine göre siler                                                                                                                    |

> **Kimlik doğrulama:** her yöntemde yönetim kimlik doğrulaması gereklidir (`requireCloudAgentManagementAuth`). v3.8.0 öncesinde bunlar kimlik doğrulamasızdı — uyumluluğu bozan değişiklik için `588a0333` commit'ine bakın.

```bash
# Bir Claude Code bulut görevi oluşturun
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'
```

---

## Yönetim Proxy'leri

Sağlayıcılara, hesaplara veya genel olarak atanabilen giden HTTP(S)/SOCKS proxy'leri.

| Yöntem | Yol                                          | Açıklama                                                                                                                                                       |
| ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Proxy'leri listeler (`?id=` ile bir tanesini, `?id=&where_used=1` ile atama grafiğini döndürür)                                                                |
| POST   | `/api/v1/management/proxies`                 | Proxy oluşturur — gövde `createProxyRegistrySchema` ile doğrulanır                                                                                             |
| PATCH  | `/api/v1/management/proxies`                 | Proxy'yi günceller — gövde `updateProxyRegistrySchema` ile doğrulanır (`id` gerektirir)                                                                        |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Proxy'yi siler (atamaları kaldırmak için `force=1` kullanın)                                                                                                   |
| GET    | `/api/v1/management/proxies/assignments`     | Atamaları listeler — `proxy_id`, `scope`, `scope_id` ile filtrelenebilir; bir bağlantının etkin proxy'sini çözümlemek için `resolve_connection_id=<id>` iletin |
| PUT    | `/api/v1/management/proxies/assignments`     | Atar — gövde `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`) ile doğrulanır. Dağıtıcı önbelleğini temizler                                             |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Toplu atama yapar — gövde `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) ile doğrulanır                                                         |
| GET    | `/api/v1/management/proxies/health?hours=24` | Belirli bir zaman aralığındaki toplu proxy durumunu (başarılı/başarısız sayıları, gecikme) döndürür                                                            |

**Kimlik doğrulama:** her rotada yönetim oturumu/API anahtarı gereklidir (`requireManagementAuth`).

> Görev açıklamasındaki `POST /api/v1/management/proxies/[id]/assignments` ve `POST /api/v1/management/proxies/[id]/health`, yukarıda gösterilen düz `/assignments` ve `/health` rotaları tarafından sunulur — kod tabanında kimlik başına alt rotalar yoktur.

---

## Dayanıklılık (genişletilmiş)

OmniRoute, birbirinden bağımsız üç geçici arıza mekanizması sunar; aşağıdaki yönetim uç noktaları, operatörlerin bunları okumasına ve geçersiz kılmasına olanak tanır:

| Kapsam                   | Durum depolaması                             | Okuma                                     | Sıfırlama / temizleme                                                    |
| ------------------------ | -------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------ |
| Sağlayıcı devre kesicisi | `domain_circuit_breakers` + bellek içi       | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                             |
| Bağlantı bekleme süresi  | Sağlayıcı bağlantılarında `rateLimitedUntil` | `/api/rate-limits`, `/api/providers/[id]` | (ihtiyaç halinde yeniden etkinleşir; sağlayıcı PUT isteğiyle temizlenir) |
| Model kilidi             | Bellek içi model kullanılabilirlik kaydı     | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                                 |

`PATCH /api/resilience`, `providerBreaker.oauth` ve `providerBreaker.apikey` altında sağlayıcı devre kesicisi geçersiz kılmalarını kabul eder. Her profil `degradationThreshold`, `failureThreshold` ve `resetTimeoutMs` alanlarını destekler; aynı alanlar Pano → Ayarlar → Dayanıklılık altında da sunulur.

```bash
# Tek bir model kilidini temizle
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# Tüm kilitleri sil
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Tam kavramsal başvuru ve kesici varsayılanları için: bkz. [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State" ve [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md).

### Hız Sınırı Kuyruğu ve Otomatik Etkinleştirme Güvenlik Ağı

- **Desteklenen yazma yolu**: Gövdesi `{"connectionId": "<id>", "enabled": true|false}` olan `POST /api/rate-limits`, bir bağlantının hız sınırı korumasını açıp kapatmak için desteklenen yönetim uç noktasıdır. `PUT /api/providers/[id]`, kasıtlı olarak `rateLimitProtection` değerini değiştirmez veya tersine çevirmez (#11278).
- **`enabled: false` anlamı**: `enabled: false` ayarı, bağlantı için açık korumayı kaldırır; ancak etkin bir API anahtarı bağlantısını genel otomatik etkinleştirme güvenlik ağının (`autoEnableApiKeyProviders = true`) dışına **çıkarmaz**. `reconcileEnabledConnections` içinde (`open-sse/services/rateLimitManager.ts`), `false` ve `undefined` eşdeğerdir; açık koruması olmayan etkin API anahtarı bağlantıları, otomatik etkinleştirme güvenlik ağı altında korunmaya devam eder.
- **Genel devre dışı bırakma**: API anahtarı bağlantılarını hız sınırı kuyrukları olmadan çalıştırmak için, güvenlik ağını genel olarak `RATE_LIMIT_AUTO_ENABLE=false` (ortam değişkeni) veya `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Ayarlar → Dayanıklılık / `PATCH /api/resilience`) ile devre dışı bırakın.

---

## Beceriler

OmniRoute'u özel çalıştırılabilir işleyicilerle genişletmeye yönelik beceri çerçevesi ve pazar yeri entegrasyonları.

| Yöntem | Yol                               | Açıklama                                                                                                                             |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/skills`                     | Yüklü becerileri listeler — `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` ile filtrelenebilir ve sayfalandırılır |
| GET    | `/api/skills/[id]`                | Tek bir beceriyi getirir                                                                                                             |
| PUT    | `/api/skills/[id]`                | Beceriyi günceller (ad, açıklama, mod, şema, işleyici, etiketler)                                                                    |
| DELETE | `/api/skills/[id]`                | Bir beceriyi kaldırır                                                                                                                |
| POST   | `/api/skills/install`             | Ham manifestten bir beceri yükler — gövde: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`            |
| GET    | `/api/skills/executions`          | Son beceri yürütmelerini listeler (girdiler/çıktılar/süre bilgilerini içeren denetim izi)                                            |
| GET    | `/api/skills/marketplace?q=...`   | SkillsMP pazar yerindeki arama/popülerlik listesini getirir (`skillsmpApiKey` ayarını gerektirir)                                    |
| POST   | `/api/skills/marketplace/install` | SkillsMP'den kimliğe göre bir beceri yükler                                                                                          |
| GET    | `/api/skills/skillssh?q=&limit=`  | skills.sh kayıt sisteminde arama yapar                                                                                               |
| POST   | `/api/skills/skillssh/install`    | skills.sh üzerinden kimliğe göre bir beceri yükler                                                                                   |

**Kimlik doğrulama:** yönetim oturumu/API anahtarı. Pazar yeri arama yolları, yönetim kimlik doğrulamasını veya Bearer API anahtarını (`isAuthenticated`) kabul eder.

---

## Bellek

API anahtarı / oturum kapsamında kalıcı konuşma/olgusal bellek deposu.

| Yöntem | Yol                  | Açıklama                                                                                                                  |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | Bellekleri listeler — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`; `offset/limit` veya `page/limit` sayfalandırmasıyla   |
| POST   | `/api/memory`        | Bellek oluşturur — gövde Zod tarafından doğrulanır: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | Tek bir belleği getirir                                                                                                   |
| DELETE | `/api/memory/[id]`   | Bir belleği siler                                                                                                         |
| GET    | `/api/memory/health` | Bellek alt sisteminin durumu (DB bağlantısı, gömme arka ucu, vektör dizini durumu)                                        |

**Kimlik doğrulama:** yönetim oturumu/API anahtarı (`requireManagementAuth`). `type` enum'u: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts` içindeki `MemoryType` bölümüne bakın).

---

## MCP Sunucusu

OmniRoute, 3 aktarım (stdio, SSE, streamable-http) ve kapsamlı araçlar içeren yerleşik bir Model Context Protocol sunucusuyla birlikte gelir. Aşağıdaki pano uç noktaları durum/denetim verilerini okur ve HTTP aktarımlarına vekillik eder.

| Yöntem | Yol | Açıklama |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Sinyal, aktarım, çevrimiçi durumu, son çağrı, en çok kullanılan araçlar, 24 saatlik başarı oranı |
| GET | `/api/mcp/tools` | `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` alanlarıyla MCP araçlarının listesi |
| GET | `/api/mcp/sse` | SSE aktarımı için SSE akışı açar (MCP devre dışıysa veya aktarım uyuşmazlığı varsa `503` döndürür) |
| POST | `/api/mcp/sse` | SSE aktarımı üzerinden JSON-RPC çerçevesi gönderir |
| GET | `/api/mcp/stream` | Streamable HTTP aktarımının SSE tarafını açar (sunucu tarafından başlatılan mesajlar) |
| POST | `/api/mcp/stream` | Streamable HTTP aktarımı üzerinden JSON-RPC çerçevesi gönderir |
| DELETE | `/api/mcp/stream` | Bir Streamable HTTP oturumunu sonlandırır |
| GET | `/api/mcp/audit` | Denetim günlüğünü sorgular — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | Toplu denetim istatistikleri (toplamlar, başarı oranı, ortalama süre, en çok kullanılan araçlar) |

**Kimlik doğrulama:** `sse`/`stream` aktarımları MCP'ye özgü kimlik doğrulama yüzeyini kullanır (`mcp` kapsamına sahip Bearer API anahtarı); `status`/`tools`/`audit*` rotaları panodan okunabilir (pano ana makinesine erişmenin ötesinde ek kimlik doğrulama gerekmez).

> Her iki HTTP aktarımı da `settings.mcpEnabled` ve `settings.mcpTransport` tarafından denetlenir — aktarım uyuşmazlığı `400`, MCP'nin devre dışı olması ise `503` döndürür.

---

## A2A Sunucusu

OmniRoute, inceleme/pano kullanımı için bir REST sarmalayıcısına ek olarak bir A2A (Agent-to-Agent) JSON-RPC 2.0 uç noktası sunar.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # OMNIROUTE_API_KEY ayarlanmadığı sürece isteğe bağlıdır
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}
```

Desteklenen yöntemler (tümü `settings.a2aEnabled` ayarına bağlıdır):

| Yöntem           | Açıklama                                                         |
| ---------------- | ---------------------------------------------------------------- |
| `message/send`   | Eşzamanlı beceri yürütme; `{task, artifacts, metadata}` döndürür |
| `message/stream` | Aynı beceri kümesinin SSE üzerinden akış yürütmesi               |
| `tasks/get`      | Bir görevi `taskId` ile getirir                                  |
| `tasks/cancel`   | Bir görevi `taskId` ile iptal eder                               |

Yerleşik beceriler: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### Aracı Kartı

```bash
GET /.well-known/agent.json
```

Herkese açık A2A aracı kartını (ad, açıklama, yetenekler, beceri kataloğu, kimlik doğrulama şeması) döndürür — herkese açık olarak 1 saat önbelleğe alınır. Kimlik doğrulama gerekmez.

### REST Yardımcıları

| Yöntem | Yol                          | Açıklama                                                                                                                |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/a2a/status`            | A2A etkinlik durumu + görev istatistikleri + önbelleğe alınmış aracı kartı özeti                                        |
| GET    | `/api/a2a/tasks`             | Görevleri listeler — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST   | `/api/a2a/tasks`             | (REST yardımcısı olarak uygulanmamıştır — JSON-RPC `message/send` aracılığıyla oluşturun)                               |
| GET    | `/api/a2a/tasks/[id]`        | Tek bir görevi getirir                                                                                                  |
| POST   | `/api/a2a/tasks/[id]/cancel` | Bir görevi iptal eder                                                                                                   |

**Kimlik doğrulama:** REST yardımcıları yönetim kimlik doğrulaması olmadan çalışır (pano tarafından okunabilir); JSON-RPC `/a2a` rotası, yapılandırılmışsa Bearer `OMNIROUTE_API_KEY` kullanır.

---

## Bulut, Değerlendirme Çalıştırmaları ve Değerlendirme

| Yöntem | Yol | Açıklama |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Bir Bearer anahtarını doğrula ve bulut senkronizasyonu istemcileri için maskelenmiş sağlayıcı bağlantılarını + model takma adlarını döndür |
| POST | `/api/cloud/credentials/update` | Bulutla senkronize edilmiş bir sağlayıcının şifrelenmiş kimlik bilgilerini güncelle |
| POST | `/api/cloud/model/resolve` | Yerel yönlendirme tablosunu kullanarak mantıksal bir model kimliğini somut bir sağlayıcı/modele çözümle |
| GET | `/api/cloud/models/alias` | Bulut senkronizasyonuna sunulan model takma adlarını listele |
| GET | `/api/assess` | En son değerlendirme sınıflandırmalarını oku (sağlayıcı/model bazında) |
| POST | `/api/assess` | Bir değerlendirme çalıştır — gövde: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Yerleşik değerlendirme paketlerini + en son çalıştırmaları listele |
| POST | `/api/evals` | Bir değerlendirme çalıştırmasını tetikle |
| POST | `/api/evals/suites` | Özel bir değerlendirme paketi oluştur — gövde `evalSuiteSaveSchema` tarafından doğrulanır |
| GET | `/api/evals/suites/[id]` | Özel bir değerlendirme paketini getir |

**Kimlik doğrulama:** `/api/cloud/auth`, bir Bearer anahtarını doğrudan doğrular ve yalnızca `manage` / `admin` kapsamına sahip bir anahtar için her bağlantının maskelenmiş anahtarını ve `projectId` değerini döndürür; diğer `/api/cloud/*`, `/api/evals/*` ve `/api/assess` rotaları yönetim oturumu/API anahtarı gerektirir. `/api/assess` POST, ayırt edici birleşim kapsam şemasıyla `validateBody` kullanır.

---

## ACP (Agent Client Protocol) Yönetimi

alt süreçler olarak. Bu uç noktalar, ACP aracılarının algılanmasını ve özel aracıların
kaydedilmesini yönetir.

| Yöntem | Yol               | Açıklama                                                                                                                                                           |
| ------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/acp/agents` | Bilinen tüm CLI aracılarını (yerleşik + özel), kurulum durumu, sürüm ve ikili dosya bilgileriyle listeler                                                          |
| POST   | `/api/acp/agents` | Özel bir ACP aracısı kaydeder veya önbelleği yeniler — gövde: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ya da `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | Özel bir ACP aracısını kaldırır — sorgu parametresi: `?id=<agentId>`                                                                                               |

**Yanıt örneği** (`GET /api/acp/agents`):

```json
{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}
```

**Kimlik doğrulama:** Yönetim oturumu (kontrol paneli `auth_token` çerezi) veya
yönetim kapsamlı bir API anahtarı gerektirir.

Tüm ayrıntılar için [ACP Framework](../frameworks/ACP.md) bölümüne bakın.

---

## Analitik ve Gözlemlenebilirlik

Yönlendirme, sıkıştırma ve sağlayıcı çeşitliliğini izlemeye yönelik gerçek zamanlı
analitik uç noktaları. Bunlar `/dashboard/analytics/*` sayfalarını destekler.

### Otomatik yönlendirme analitiği

| Yöntem | Yol                                  | Açıklama                                                                                                          |
| ------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/auto-routing`        | Toplu otomatik yönlendirme istatistikleri: toplam çağrı, strateji dağılımı, katman dağılımı, başlıca sağlayıcılar |
| GET    | `/api/analytics/auto-routing?days=7` | Zaman pencereli istatistikler (varsayılan 24 sa.)                                                                 |

**Yanıt örneği**:

```json
{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}
```

### Sıkıştırma analitiği

| Yöntem | Yol                          | Açıklama                                                                                                    |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/compression` | Toplu sıkıştırma istatistikleri: tasarruf edilen token'lar, tasarruf yüzdesi, mod dağılımı, motor kullanımı |

**Yanıt örneği**:

```json
{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}
```

### Sağlayıcı çeşitliliği takibi

| Yöntem | Yol                        | Açıklama                                                                                             |
| ------ | -------------------------- | ---------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/diversity` | Shannon entropisi tabanlı çeşitlilik takibi: sağlayıcı dağılımını ölçerek tek hata noktalarını önler |

**Yanıt örneği**:

```json
{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI trafiğin %40'ını oluşturuyor — çeşitlendirmeyi değerlendirin"]
}
```

**Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı bir API anahtarı gerektirir.

---

## Yönetici İşlemleri

Operasyonel yönetim için yalnızca yöneticilere açık uç noktalar.

| Yöntem | Yol                      | Açıklama                                                                                             |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | Mevcut eşzamanlılık sınırlarını oku (genel + sağlayıcı başına)                                       |
| POST   | `/api/admin/concurrency` | Eşzamanlılık sınırlarını güncelle — gövde: `{global?: number, perProvider?: Record<string, number>}` |

**Kimlik doğrulama:** Yönetici kapsamına sahip bir yönetim oturumu gerektirir.

---

## CLI Araçları Yönetimi

OmniRoute ile entegre olan CLI araçlarını (antigravity, commandCode,
devin-cli vb.) yönetin. Tam liste için [Sağlayıcı Referansı](./PROVIDER_REFERENCE.md) sayfasına bakın.

| Yöntem | Yol                                     | Açıklama                                                                                                                                                                                |
| ------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cli-tools/all-statuses`           | Tüm CLI araçlarının durumu (yüklü olma durumu, sürüm, son görülme zamanı)                                                                                                               |
| GET    | `/api/cli-tools/status`                 | Tek bir CLI aracının durum ayrıntıları (`?tool=` sorgusu)                                                                                                                               |
| POST   | `/api/cli-tools/apply`                  | Bir aracın oluşturulan yapılandırmasını yazar (`dryRun` önizleme yapar; konteynerleştirilmişse `422` + `containerEphemeralTarget`; `migration`, eski bir Codex YAML dosyasını belirtir) |
| GET    | `/api/cli-tools/backups`                | CLI aracı yapılandırma yedeklerini listeler                                                                                                                                             |
| POST   | `/api/cli-tools/backups`                | Tüm CLI aracı yapılandırmalarının yedeğini oluşturur                                                                                                                                    |
| POST   | `/api/cli-tools/backups`                | Geri yükleme: gövdesinde `{tool, backupId}` ile aynı uç nokta, ilgili yedeği geri yükler                                                                                                |
| GET    | `/api/cli-tools/antigravity-mitm`       | Antigravity MITM proxy durumu ("antigravity-mitm" CLI aracı)                                                                                                                            |
| POST   | `/api/cli-tools/antigravity-mitm/alias` | antigravity-mitm takma adlarını yapılandırır                                                                                                                                            |

**Kimlik doğrulama:** Yönetim oturumu gerektirir.

---

## Aracı Becerileri

Yapay zekâ aracı becerilerini yönetin (OpenAI'ın özel GPT'lerine benzer, ancak aracılar içindir).

| Yöntem | Yol                          | Açıklama                                                                                     |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Tüm aracı becerilerini listele (yerleşik + özel)                                             |
| GET    | `/api/agent-skills/[id]`     | Belirli bir aracı becerisini getir                                                           |
| POST   | `/api/agent-skills`          | Özel bir aracı becerisi oluştur — gövde: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Özel bir aracı becerisini güncelle                                                           |
| DELETE | `/api/agent-skills/[id]`     | Özel bir aracı becerisini sil                                                                |
| GET    | `/api/agent-skills/[id]/raw` | Ham istemi + meta verileri getir (çalıştırma yok)                                            |
| POST   | `/api/agent-skills/generate` | Doğal dil açıklamasından yapay zekâ ile yeni bir beceri oluştur                              |

**Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı API anahtarı gerektirir.

---

## Önbellek Yönetimi

Anlamsal önbelleği ve akıl yürütme önbelleğini yönetin.

| Yöntem | Yol                    | Açıklama                                                                                                                        |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Önbelleğe genel bakış: toplam kayıt sayısı, isabet oranı, diskteki boyut                                                        |
| GET    | `/api/cache/entries`   | Önbelleğe alınmış kayıtları listele (sayfalandırma ile)                                                                         |
| DELETE | `/api/cache/entries`   | Önbellek kayıtlarını sil (sorgu parametrelerine göre filtrele)                                                                  |
| GET    | `/api/cache/stats`     | Ayrıntılı önbellek istatistikleri (sağlayıcı ve model bazında)                                                                  |
| GET    | `/api/cache/reasoning` | Akıl yürütme önbelleğinin durumu (akıl yürütmeyi yeniden oynatmak için)                                                         |
| DELETE | `/api/cache/reasoning` | Akıl yürütme önbelleğini temizle — sorgu parametreleri: `?toolCallId=<id>` (tek) veya `?provider=<p>` ya da parametresiz (tümü) |

**Kimlik doğrulama:** Yönetim oturumu gerektirir.

---

## Bellek Sistemi

Kalıcı belleği (FTS5 + vektör gömmeleri) yönetin.

| Yöntem | Yol                | Açıklama                                                                    |
| ------ | ------------------ | --------------------------------------------------------------------------- |
| GET    | `/api/memory`      | Bellek kayıtlarını listele (kapsama, türe ve arama sorgusuna göre filtrele) |
| POST   | `/api/memory`      | Yeni bir bellek kaydı oluştur — gövde: `{scope, type, content, metadata?}`  |
| GET    | `/api/memory/[id]` | Belirli bir bellek kaydını getir                                            |
| PUT    | `/api/memory/[id]` | Bir bellek kaydını güncelle                                                 |
| DELETE | `/api/memory/[id]` | Bir bellek kaydını sil                                                      |
| GET    | `/api/memory?q=`   | Bellekte ara (FTS5 + vektör) — istatistikler aynı yanıta dahil edilir       |

**Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı API anahtarı gerektirir.

---

## Webhook'lar

Olaylara yönelik webhook aboneliklerini yönetin.

| Yöntem | Yol                             | Açıklama                                                                   |
| ------ | ------------------------------- | -------------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | Tüm webhook aboneliklerini listele                                         |
| POST   | `/api/webhooks`                 | Bir webhook aboneliği oluştur — gövde: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | Belirli bir webhook aboneliğini getir                                      |
| PUT    | `/api/webhooks/[id]`            | Bir webhook aboneliğini güncelle                                           |
| DELETE | `/api/webhooks/[id]`            | Bir webhook aboneliğini sil                                                |
| GET    | `/api/webhooks/[id]/deliveries` | Bir webhook'un teslimat geçmişini listele (başarı/başarısızlık günlüğü)    |
| POST   | `/api/webhooks/[id]/test`       | Bir webhook'a test olayı gönder                                            |

**Kimlik doğrulama:** Yönetim oturumu gerektirir.

Tüm olay türleri için [Webhook Çerçevesi](../frameworks/WEBHOOKS.md) bölümüne bakın.

---

## Skills Çerçevesi

Skills'leri (otonom eklentiler çerçevesi) yönetin.

| Yöntem | Yol                      | Açıklama                                                                                                         |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Yüklü tüm Skills'leri listeleyin (yerleşik + özel)                                                               |
| POST   | `/api/skills/install`    | Yerel bir yoldan veya URL'den Skill yükleyin                                                                     |
| DELETE | `/api/skills/[id]`       | Bir Skill'i kaldırın                                                                                             |
| PUT    | `/api/skills/[id]`       | Bir Skill'i etkinleştirin veya devre dışı bırakın — gövde: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Bir Skill çalıştırın — gövde: `{skillName, apiKeyId, input?, sessionId?}`                                        |
| GET    | `/api/skills/executions` | Tüm Skills'lerin yürütme geçmişini listeleyin (`?apiKeyId=` ile filtreleyin)                                     |

**Kimlik doğrulama:** Yönetim oturumu veya yönetim kapsamlı API anahtarı gerektirir.

Tüm ayrıntılar için [Skills Çerçevesi](../frameworks/SKILLS.md) belgesine bakın.

---

## Eklentiler

OmniRoute eklentilerini (üçüncü taraf uzantıları) yönetin.

| Yöntem | Yol                                | Açıklama                             |
| ------ | ---------------------------------- | ------------------------------------ |
| GET    | `/api/plugins`                     | Yüklü eklentileri listeleyin         |
| POST   | `/api/plugins/marketplace/install` | Pazaryerinden bir eklenti yükleyin   |
| DELETE | `/api/plugins/[name]`              | Bir eklentiyi kaldırın               |
| POST   | `/api/plugins/[name]/activate`     | Bir eklentiyi etkinleştirin          |
| POST   | `/api/plugins/[name]/deactivate`   | Bir eklentiyi devre dışı bırakın     |
| GET    | `/api/plugins/[name]/config`       | Eklenti yapılandırmasını alın        |
| PUT    | `/api/plugins/[name]/config`       | Eklenti yapılandırmasını güncelleyin |

**Kimlik doğrulama:** Yönetim oturumu gerektirir.

Tüm ayrıntılar için [Eklentiler Çerçevesi](../frameworks/PLUGIN_SDK.md) belgesine bakın.

---

## Gölge Yönlendirme

Sağlayıcıların gölge / A-B karşılaştırması **bağımsız bir REST yüzeyi değildir** — birleşik yönlendirme aracılığıyla yapılandırılır (bkz. [Otomatik Birleşim](../routing/AUTO-COMBO.md)). Birleşim başına karşılaştırma metrikleri `GET /api/combos/metrics` tarafından sunulur.

---

## Koruma Mekanizmaları

Çalışma zamanı koruma mekanizmalarını (PII algılama, istem enjeksiyonu algılama, görsel köprüleme) inceleyin. Koruma mekanizmaları her istekte çalışır; çağrı bazında devre dışı bırakma işlemi `x-omniroute-disabled-guardrails` istek başlığı aracılığıyla yapılır — kalıcı bir etkinleştirme/devre dışı bırakma yüzeyi yoktur.

| Yöntem | Yol                    | Açıklama                                                                                                             |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/guardrails`      | Kayıtlı koruma mekanizmalarını ve durumlarını listeleyin (ad / etkin / öncelik)                                      |
| POST   | `/api/guardrails/test` | Çağrı öncesi işlem hattını örnek bir girdi üzerinde deneme amaçlı çalıştırın — gövde: `{input, disabledGuardrails?}` |

**Kimlik doğrulama:** Yönetim oturumu gerektirir.

Tüm ayrıntılar için [Güvenlik > Koruma Mekanizmaları](../security/GUARDRAILS.md) belgesine bakın.

---

---

## Kimlik Doğrulama

Dört kimlik bilgisi ailesi (gösterge paneli oturumu, yerel CLI token'ı, `oma_live_…` Erişim Token'ı, yönetim kapsamlı API anahtarı) ve bunların çıkarım anahtarlarından farkları için [Yönetim Kimlik Doğrulaması](../guides/MANAGEMENT-AUTH.md) bölümüne bakın.

- Gösterge paneli rotaları (`/dashboard/*`) `auth_token` çerezini kullanır
- Giriş işlemi, kaydedilmiş parola karmasını kullanır; mevcut değilse `INITIAL_PASSWORD` kullanılır
- `requireLogin`, `/api/settings/require-login` üzerinden açılıp kapatılabilir
- `/v1/*` rotaları, `REQUIRE_API_KEY=true` olduğunda isteğe bağlı olarak Bearer API anahtarı gerektirir
- Bu referanstaki "yönetim token'ı" / "yönetim kapsamlı API anahtarı", ilgili kılavuzdaki ailelerden birini ifade eder — tanımlanmamış ek bir gizli bilgi türünü değil

> **Geriye dönük uyumluluğu bozan değişiklik (v3.8.0)** — `/api/v1/agents/tasks/*` ve bekleme süresi yönetimi uç noktaları artık **yönetim kimlik doğrulaması** (gösterge paneli `auth_token` çerezi veya yönetim kapsamlı bir API anahtarı) gerektirir. Daha önce bu rotaları kimlik doğrulaması olmadan çağıran istemciler `401 Unauthorized` yanıtını alacaktır. `588a0333` (`fix(auth): temsilci ve bekleme süresi API'leri için yönetim kimlik doğrulaması gerektir`) commit'ine bakın.