# 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:** 🇺🇸 [İngilizce](./API_REFERENCE.md) | 🇪🇹 [Amharca](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [Arapça](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azerbaycanca](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Bulgarca](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [Bengalce](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Boşnakça](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Çekçe](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Danca](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Almanca](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Yunanca](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [İspanyolca](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Estonca](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [Farsça](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Fince](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Fransızca](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [İrlandaca](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [Guceratça](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausaca](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [İbranice](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [Hintçe](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hırvatça](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Macarca](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Ermenice](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Endonezce](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [İgboca](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [İtalyanca](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [Japonca](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [Gürcüce](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [Khmerce](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [Kannadaca](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [Korece](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Litvanca](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Letonca](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [Malayalamca](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [Marathice](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Malayca](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Maltaca](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [Birmanca](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [Nepalce](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Felemenkçe](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norveççe](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [Odiyaca](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [Pencapça](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipince](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Lehçe](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Portekizce (Portekiz)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Portekizce (Brezilya)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Rumence](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Rusça](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [Seylanca](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovakça](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovence](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Sırpça](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [İsveççe](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Svahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [Tamilce](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [Teluguca](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [Tayca](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Ukraynaca](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [Urduca](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Özbekçe](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Vietnamca](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorubaca](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [Basitleştirilmiş Çince](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [Geleneksel Çince](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

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

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

Her dağıtım, derleme sırasında `docs/openapi.yaml` dosyasından oluşturulan spesifikasyonun kendi kopyasını `/openapi.yaml` adresinde sunar. Bu kopya, derlemenin sürümünü ve göreli bir sunucu URL'sini (`./`) içerir; böylece istekler belgeyi sunan ana bilgisayarda kalır. İndirilen dosyayı içe aktaran bir araçta böyle bir ana bilgisayar bilgisi bulunmaz ve temel URL'nin elle ayarlanması gerekir.

---

## İçindekiler

- [Sohbet Tamamlama](#chat-completions)
- [Özel Yönetilen Oturum Kiralamaları](#exclusive-managed-session-leases)
- [Gömüler](#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)
- [Files API](#files-api)
- [Batches API](#batches-api)
- [Search API](#search-api)
- [WebSocket Akışı](#websocket-streaming)
- [Kotalar ve Sorun Bildirimi](#quotas--issues-reporting)
- [Anlamsal Önbellek](#semantic-cache)
- [CLIProxyAPI Yönetim Uyumluluğu](#cliproxyapi-management-compatibility)
- [Kontrol Paneli ve Yönetim](#dashboard--management)
- [Kombinasyon Yönetimi](#combo-management)
- [Web Kancaları](#webhooks)
- [Kayıtlı Anahtarlar (Otomatik Yönetim)](#registered-keys-auto-management)
- [Aracılar 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)
- [Cloud, Evals ve Assess](#cloud-evals--assess)
- [İstek İşleme](#request-processing)
- [Kimlik Doğrulama](#authentication)

---

## Sohbet Tamamlama

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "Write a function to..."}
  ],
  "stream": true
}
```

### Özel Üst Bilgiler

| Header                   | Direction | Description                                                                                                                                                                                                                               |
| ------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | İstek     | Önbelleği devre dışı bırakmak için `true` olarak ayarlayın                                                                                                                                                                                |
| `x-omniroute-no-memory`  | İstek     | Bu istek için bellek + beceri enjeksiyonunu atlamak üzere `true` olarak ayarlayın (no-cache davranışını yansıtır; çağrı başına token/maliyet ek yükünü önler)                                                                             |
| `X-OmniRoute-Progress`   | İstek     | İlerleme olayları için `true` olarak ayarlayın                                                                                                                                                                                            |
| `X-Session-Id`           | İstek     | Harici oturum bağlılığı için sabit oturum anahtarı                                                                                                                                                                                        |
| `x_session_id`           | İstek     | Alt çizgili varyant da kabul edilir (doğrudan HTTP)                                                                                                                                                                                       |
| `X-OmniRoute-Session-Id` | İstek     | Çağıran tarafından sağlanan oturum/konuşma etiketi (belleğe de aktarılır). Mevcut olduğunda, oturum başına maliyet ilişkilendirmesi için `call_logs.session_tag` alanına olduğu gibi kaydedilir (#8249) — yoksa hiçbir zaman sentezlenmez |
| `Idempotency-Key`        | İstek     | Yinelenen istekleri ayırt etme anahtarı (5 saniyelik pencere)                                                                                                                                                                             |
| `X-Request-Id`           | İstek     | Alternatif yinelenen istekleri ayırt etme anahtarı                                                                                                                                                                                        |
| `x-omniroute-connection` | İstek     | Tek modelli bir isteği kimliğiyle belirli 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 isteklerin ayıklandığını belirtmek için `true`                                                                                                                                                                                  |
| `X-OmniRoute-Progress`   | Yanıt     | İlerleme takibi etkinse `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 mevcut)                                                                                                                                                                                               |
| `X-OmniRoute-Cost-Saved` | Yanıt     | Önbellek isabetinde önlenen USD tutarı (yalnızca önbellek isabetlerinde)                                                                                                                                                                  |
| `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` değerini alır) — tamamlama yanıtlarında her zaman bulunur                                  |

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

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

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

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

- **Kimliği nerede bulabilirsiniz?** Panoda sağlayıcı sayfasını açın
  (**Panel → Sağlayıcılar → <provider>**) ve bir bağlantı satırındaki `xxxxxxxx…` kimlik çipine
  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 model istekleri (`provider/model`). Kombinasyonlar başlığı yok
  sayar: her kombinasyon adımı için bir hesabı, adımın kendi bağlantısı üzerinden sabitleyin.
- **Sabitleme bir tercih değil, kesin bir kuraldır.** Sabitlenen bağlantı yalnızca kendisi
  kullanılır. İstek içinde gerçekleşen bir hata, hesabın bekleme süresini kaydeder ancak aynı
  sağlayıcıdaki kardeş hesaba geçiş yapmaz.
- **Bekleme süresi ve kota sabitlemeyi kaldırır.** Sabitlenen bağlantı bekleme süresindeyken,
  kota tükenmişse veya bir kota politikası tarafından engellenmişse sonraki istekler, sabitlenmemiş
  trafikle tamamen aynı şekilde sağlayıcının diğer bağlantılarına geri döner.
- **Bilinmeyen veya devre dışı 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 yere yönlendirilmek yerine başarısız olur.

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

```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ık okuma), `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 de taşır — `X-OmniRoute-Response-Cost` (USD, sabit 10 ondalık basamak; ücretsiz/fiyatlandırılmamış 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'dan büyük olduğunda), ayrıca `X-OmniRoute-Request-Id` ve `X-OmniRoute-Version`. Bunlar sohbet tamamlamaları, `/v1/responses`, `/v1/messages` **ve medya uç noktaları** — `/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`) — tarafından gönderilir. Medya maliyeti, fiyatlandırma mevcut olduğunda modalite başına (görüntü başına, saniye başına, karakter başına, arama birimi başına) hesaplanır; aksi takdirde `0` olur (fail-open).

> **Önbellek isabeti maliyet semantiği:** anlamsal önbellek İSABETİ (`X-OmniRoute-Cache-Hit: true`) durumunda üst akışa çağrı yapılmaz; bu nedenle `X-OmniRoute-Response-Cost`, isabeti sunmanın **artımlı** maliyeti olarak `0.0000000000` olur. Orijinal/oluşacak maliyet ayrı olarak `X-OmniRoute-Cost-Saved` içinde bildirilir. Faturalandırma tüketicileri `X-OmniRoute-Response-Cost` değerlerini toplamalıdır (isabetlerin maliyeti yoktur); önbellek analizleri `X-OmniRoute-Cost-Saved` değerlerini bir araya getirebilir.

## Özel Yönetilen Oturum Kiraları

Özel yönetilen oturum kiralama, isteğe bağlı, istemciden bağımsız bir yönlendirme sözleşmesidir: tek bir etkin sahip,
uygun bir OmniRoute bağlantısını elinde tutar. Bir model kiralamaz, OAuth gerektirmez, belirli bir istemciyi
tanımlamaz veya belirli bir sağlayıcı gerektirmez.

Kimlik doğrulaması yapan API anahtarı `lease:exclusive` kapsamına ve açık, boş olmayan bir
`allowedConnections` listesine sahip olmalıdır. Veritabanı değişikliği sınırı, anahtar oluşturma ve kısmi
güncellemelerde her iki alanın birlikte bulunmasını zorunlu kılar.

```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 bırakma yanıtları zaman damgalarını, `state` değerini ve tam pozitif
`generation` değerini gösterir; ancak seçilen bağlantıyı veya kimlik bilgilerini hiçbir zaman göstermez. Yenileme
ve bırakma işlemleri `generation` değerini JSON gövdesinde sağlar:

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

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

Etkin bir oturum sahibi, mevcut bağlaması için gizlilik açısından güvenli görüntüleme meta verilerini açıkça
isteyebilir:

```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 işlemi, opak sahip, kimliği doğrulanmış yönetilen API anahtarı ve tam etkin
generation değerleriyle tek bir veritabanı işlemi içinde sınırlandırılır. `displayName` yalnızca kırpılmış,
yapılandırılmış bağlantı adıdır; güvenli yapılandırılmış bir ad bulunmadığında `null` olur. OmniRoute hiçbir zaman
bir e-posta adresini veya oluşturulmuş hesap kimliğini bunun yerine kullanmaz. Sağlayıcı değeri hassas olmayan
bir görüntüleme etiketidir ve hiçbir zaman 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ı, çitleme sırları ve dahili
yönlendirme verileri hariç tutulur.

Yanlış anahtar, yanlış sahip, eski generation, eksik, süresi dolmuş, bırakılmış ve geçersizleştirilmiş aramalar,
bağlantı meta verileri olmadan aynı `409 LEASE_FENCE_STALE` hatasını döndürür. Kapasite bekleme yanıtını alan bir
istemcinin inceleyebileceği etkin bir bağlaması yoktur. Yönlendirme etkin bir kirayı geçirdiğinde aynı generation
geçerli kalır ve durum atomik olarak yeni bağlamayı döndürür; eski bağlamayı hiçbir zaman döndürmez. Edinme,
yenileme, bırakma ve bekleme yanıtları önceki şekillerini koruduğundan mevcut istemciler değişmeden kalır.

Bu sunucu sözleşmesi, standart OpenAI Codex `/status` davranışını değiştirmez. Standart Codex şu anda model
sağlayıcısını ve yerleşik kimlik doğrulama/hesap durumunu bildirir; ancak isteğe bağlı özel sağlayıcı hesap
meta verilerini görüntülemez. Daha sonraki bir istemci entegrasyonu bu işlemi çağırmalı ve
`connection.displayName` değerinin nasıl görüntüleneceğine karar vermelidir.

Bundan sonra her yönetilen çıkarım isteği her iki denetim üstbilgisini de sağlar:

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

Tam sahip, generation, etkin bağlantı ve kimliği doğrulanmış API anahtarı, desteklenen her üst akış denemesinden
hemen önce sınırlandırılır. Sahip ve generation değerlerinin başka bir anahtarla yeniden oynatılması, bu anahtar
aynı bağlantıya izin verse bile başarısız olur. Ham sahipler kalıcı olarak saklanmaz, günlüğe yazılmaz, istek
anlık görüntüsünde tutulmaz veya üst akışa iletilmez.

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

```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 normal uygun kümenin boş olmadığını ve tüm boş adayların başka bir etkin kiraya sahip yabancı
sahipler tarafından tutulduğunu belirtir. Desteklenmeyen modeller/sağlayıcılar, politika uyuşmazlığı, bekleme
süresi, kota, sağlık durumu ve diğer normal 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 önceliğe sahiptir — yönlendirme birleşimi
geçersiz kılmasının, etkin profilin, otomatik tetiklemenin ve paneldeki Default değerinin önüne geçer.

| Değer         | Etki                                                                                             |
| ------------- | ------------------------------------------------------------------------------------------------ |
| `off`         | Bu istek için sıkıştırma yoktur.                                                                 |
| `default`     | Panelden türetilen Default profili (etkin profili yok sayar). Kayıplı motorlar kapalı bırakılır. |
| `safe`        | Yalnızca yinelenenleri kaldırma ve boşluk katlama.                                               |
| `allow-lossy` | Özetler ve stil yeniden yazımları dahil olmak üzere operatör planını bu istek için korur.        |
| `engine:<id>` | Etkin olduğunda tek bir motor; ör. `engine:rtk`. Bu motor için istek başına etkinleştirme.       |
| `<combo>`     | Adla (büyük/küçük harfe duyarsız) ve ardından kimlikle eşleştirilen adlandırılmış bir birleşim.  |

Notlar:

- Bilinmeyen değerler yok sayılır (istek hiçbir zaman reddedilmez); çözümleme normal operatör önceliğine geri döner.
- Birden çok birleşim aynı adı paylaşıyorsa deterministik bir eşleşme için birleşim **id** değerini iletin.
- Adı `off` veya `default` olan bir birleşim adla seçilemez (bu anahtar sözcükler önce yorumlanır); böyle bir birleşime kimliğiyle başvurun.
- Ana sıkıştırma anahtarı kesin bir geçittir: sıkıştırma genel olarak devre dışı bırakıldığında bu üstbilgi onu etkinleştiremez.

Uygulanan plan, yanıt üstbilgisinde geri yansıtılır:

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

Burada `<source>` şu değerlerden biridir: `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default` veya `off`.

---

## Embedding'ler

```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ıtta görünen yalın Jina model kimlikleri (örneğin `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) de çö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 panelinde anahtar yoksa yedek olarak kullanılır. `jina-reader` kartı yalnızca Reader / `r.jina.ai` içindir (`POST /v1/web/fetch`) ve hiçbir zaman embedding veya rerank hizmeti sunmaz.

Çok modlu desteği bildiren kayıt 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` değerleridir. 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 takma adı `jina-ai/jina-embeddings-v5-omni` → omni-small), Jina'nın yerel EmbeddingsV5Request belgelerini de kabul eder ve bunları olduğu gibi `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 dizgeleştirmez ya da yerel image URL'lerini getirmez — Jina herkese açık medyayı kendisi alır. Ek Jina alanları (`task`, `normalized`, `truncate`, `embedding_type`) iletilir. Yalnızca metin destekleyen Jina SKU'ları, metin dışı belgeleri yine reddeder.

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

- Uzak medya URL'leri herkese açık HTTPS olmalıdır. Kanonik `{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 uygulanır) ve sağlayıcı çağrısından önce satır içine yerleştirilir. Jina yerel `{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 kodu çözülmüş 8 MiB ve istek genelinde kodu çözülmüş 16 MiB ile sınırlıdır.

Sağlayıcı çevirisi (kanonik öğeler hiçbir zaman değiştirilmeden iletilmez):

- Jina çok modlu modelleri: her üst düzey öğe, satır içi medya için data URI'leri kullanılarak tek bir modality-keyed nesneye (`text` / `image` / `audio` / `video` / `pdf`) dönüştürülür; üst düzey öğe başına bir vektör oluşturulur.
- Gemini Embedding 2 ailesi: tek 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 tüm modeller): kanonik `text` öğeleri düz dizelere dönüştürülür; `image` / `audio` / `video` öğelerinin her biri, satır içi veriler kullanılarak llama-server'ın sohbet içerik parçalarıyla (`image_url`, `format` değeri `wav` / `mp3` / `flac` olan `input_audio`, `input_video`) bir `{"content": [part]}` nesnesine dönüştürülür; üst düzey öğe başına bir vektör oluşturulur. Sunucu `--embedding --mmproj …` ile çalıştırılmalıdır; projektör olmadan medyayı kendisi reddeder. `document` desteklenmez.
- Açık modality meta verileri olmayan 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/modality birleşimleri, öğeyi zorla dönüştürmek yerine HTTP 400 döndürür. Eski dize/token isteklerindeki giriş dışı uzantı alanları değişmeden iletilmeye devam eder.

```bash
# Tüm embedding modellerini listele
GET /v1/embeddings
```

---

## Görüntü Üretimi

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

{
  "model": "openai/gpt-image-2",
  "prompt": "A beautiful sunset over mountains",
  "size": "1024x1024"
}
```

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

`n` `n` görüntülerini `data[]` biçiminde döndürür. Yukarı akış API çağrı başına bir görüntü döndüren sağlayıcılar (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolik, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI), uçuş sırasında en fazla 4 olmak üzere `n` ayrı yukarı akış çağrıları alır. Sabit bir `seed` çağrı dizini (`seed`, `seed + 1`, …) ile dengelenir, böylece görüntüler farklılık gösterir ancak tekrarlanabilir kalır. `n` sınırı 10'dur. Herhangi bir çağrı başarısız olursa istek bir bütün olarak başarısız olur. Yayılma formatlarının listesi `open-sse/handlers/imageGeneration/fanOut.ts` içindeki `SINGLE_IMAGE_FANOUT_FORMATS` şeklindedir.

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

- `zenmux/openai/gpt-image-2`, ZenMuxOpenAI Görüntüleri API 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 Vertex AI `:predict` uç noktasını kullanır. `n`, `sampleCount` ile, `aspect_ratio`, `aspectRatio` ile ve `image_size` (`1K`, `2K`, `4K`) `sampleImageSize` ile eşleşir. Bir piksel `size` yalnızca en boy oranını sağlar, piksel boyutlarını garanti etmez. Desteklenen oranlar, çözünürlükler ve sayımlar modele göre değişir.
- `zm/inclusionai/ming-image-0.1-design` kendi boyutlarını seçer. `size`, `aspect_ratio` ve `image_size` atlayın; açık değerler HTTP 400 değerini döndürür. PNG, JPEG ve WebP `output_format` ile istenebilir.

Bu entegrasyon, referans görüntü düzenlemeyi değil, metinden görüntüye oluşturmayı destekler. Vertex çıktısı `data[].b64_json` normalleştirildi; `response_format: "url"` yalnızca görüntü baytları mevcut olduğunda yukarı akışlı bir HTTPS URL veya bir base64 verisi URL döndürür. Empty/filtered çıktıları boş başarı yerine hata döndürür. Model erişimi ZenMux hesabına bağlıdır. [ZenMux Vertex API](https://docs.zenmux.ai/api/vertexai/generate-images) ve [OpenAI Görüntülerine bakın API](https://docs.zenmux.ai/api/openai/generate-an-image).

Microsoft 365 Copilot oturum açma bağlantısı, Copilot yerleşik görüntü aracı aracılığıyla `copilot-m365-web/m365-copilot-image` hizmet eder: görüntü başına bir Copilot dönüşü (`n` 1–4), `size` yalnızca yönlendirmeyi yönlendirir ve satır içi döndürülen görüntüler (`b64_json` veya `response_format: "url"` için bir veri URL ). Bkz. [Microsoft 365 Copilot](../providers/COPILOT-M365.md#image-generation).

```bash
# List all image models
GET /v1/images/generations
```

---

## Belge OCR'si

```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`, `provider/model` ön eki aracılığıyla OCR sağlayıcısını seçer; yalın bir model kimliği (ör.
`mistral-ocr-latest`), kayıtlı sağlayıcısına çözümlenir ve `model` belirtilmezse 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 yalın `mistral-ocr-latest`) | Eşzamanlı — yanıt, tek üst seviye çağrıdan doğrudan döndürülür.                                                              |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                    | Eşzamansız üst seviye işlem (`analyze` + yoklama) — aşağıya bakın.                                                           |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                        | Vertex AI'nin `openapi/chat/completions` iş ortağı uç noktası üzerinden eşzamanlı — kimlik doğrulama/URL için aşağıya bakın. |

Her üç sağlayıcı da aynı Mistral biçimli 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 bir gövde yerine
`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 30 denemeye kadar her saniye 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â çalışıyorsa `504` döndürür. Son Azure yanıtı, çağırana döndürülmeden önce Mistral tarafından kullanılan aynı
`pages`/`markdown` biçiminde 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ümleme

`vertex-deepseek-ocr`, OmniRoute'un sohbet/görüntü 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ı, bir Hizmet Hesabı JSON kimlik bilgisi
(JWT-bearer akışı aracılığıyla kısa ömürlü bir OAuth erişim belirteciyle değiştirilir) veya olduğu gibi kullanılan
önceden oluşturulmuş bir OAuth erişim belirteci olabilir. Üst seviye uç nokta URL'si, bağlantının projesi ve
bölgesinden oluşturulan Vertex'in genel `openapi/chat/completions` iş ortağı uç noktasıdır —
açıkça belirtilen bir `providerSpecificData.project`/`providerSpecificData.region` her zaman önceliklidir;
aksi durumda proje, Hizmet Hesabı JSON'undaki `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
`src/app/api/v1/ocr/route.ts` tarafından `handleOcr`'a gönderilmeden önce kullanılır.

---

## Modelleri Listeleme

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

→ OpenAI biçiminde tüm sohbet, embedding ve görüntü modellerini + birleşimleri döndürür
```

### Model fiyatları (`pricing`)

OmniRoute modelin fiyatını biliyorsa bir giriş `pricing` nesnesi içerir. Fiyat, maliyet
hesaplamasının kullandığı fiyatlandırma tablosundan gelir: yerleşik varsayılanlar, eşitlenen fiyatlar ve
`/api/pricing` üzerinden belirlenen geçersiz kılmalar. Bunlar liste fiyatlarıdır; bu nedenle abonelik sağlayıcıları
da token başına fiyat gösterir.

```json
"pricing": {
  "prompt": "0.000005",
  "completion": "0.000025",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625",
  "input": 5,
  "output": 25,
  "cached": 0.5,
  "cache_creation": 6.25
}
```

| Alanlar                                                         | Birim                           | Notlar                                                                                                                                                  |
| --------------------------------------------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`, `completion`, `input_cache_read`, `input_cache_write` | Token başına USD, ondalık dize  | OpenRouter uyumlu; hiçbir zaman üstel gösterimde değildir. İki önbellek alanı yalnızca bir önbellek fiyatı olduğunda görünür.                           |
| `input`, `output`, `cached`, `cache_creation`                   | 1 milyon token başına USD, sayı | Daha önceki katalog sürümlerindeki alanlar; mevcut istemciler için korunmuştur. Fiyatlandırma satırında varsa `reasoning` ve `long_context` da görünür. |

- **Birleşimler**, ilk görünür hedeflerinin fiyatını taşır. Yerleşik `auto/*` birleşimleri istek
  sırasında bir hedef seçer; bu nedenle `pricing` bilgileri yoktur.
- **Ücretsiz modeller**, fiyatları sıfır olduğunda `"0"` (ve `0`) gösterir. Fiyatlandırma satırı olmayan bir model,
  katalog onu ücretsiz olarak işaretliyorsa (`free: true`) veya yerleşik ücretsiz model
  kataloğunda listeleniyorsa yine `"0"` gösterir.
- **Bilinmeyen fiyat:** girişte `pricing` anahtarı bulunmaz.
- **Kredi ölçümlü sağlayıcılar** (örneğin Kiro), token başına değil istek başına ücretlendirir. Bu sağlayıcıların
  girişleri daha önce sahip oldukları 1 milyon token başına sayısal alanları korur ve token başına dize alanları taşımaz.
- **Varyantlar** (reasoning-effort kimlikleri, düşünme özelliği olmayan takma adlar, keşif ve ağ geçidi yansıları),
  yönlendirdikleri modelin fiyatını kopyalar.
- Alanlar yalnızca temel ücretleri taşır. Uzun bağlam katmanları (sayısal `long_context` alanı) ve
  hizmet katmanı çarpanları (örneğin Codex fast veya flex), `prompt` ya da
  `completion` değerlerini değiştirmez.
- Nesne, `x-api-key` ve `anthropic-version` kullanan Anthropic tarzı istek dahil olmak üzere her kimlik doğrulama
  biçimi için aynıdır (yanıt `{ "object": "list",
"data": [...] }` olarak kalır). Uygulama: `src/app/api/v1/models/catalogPricing.ts`.

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

Çoğu model bir **sağlayıcı ön eki** altında duyurulur. Hangi ön eki alacağınız
`MODELS_CATALOG_PREFIX_MODE` özellik bayrağı tarafından kontrol edilir ve istek başına bir sorgu parametresiyle
geçersiz kılınabilir — sunucu genelindeki ayarı herkes için değiştirmeden temiz bir liste isteyen bir istemci için 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         | Yayınlar                                                 | 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. Katalog yaklaşık iki katına çıkar.         |
| `alias`     | `cc/claude-sonnet-4-6`                                   | Model başına bir giriş. Farklı bir takma adı olmayan sağlayıcılar da girişlerini yayınlar; bu nedenle hiçbir şey kaybolmaz.                                                                                 |
| `canonical` | `claude/claude-sonnet-4-6`                               | Model başına tam sağlayıcı kimliği ön eki altında bir giriş. Farklı bir takma adı olmayan sağlayıcılar (ör. `antigravity/…`, `agy/…`) da tek kimliklerini burada yayınlar; bu nedenle hiçbir şey kaybolmaz. |

`dual` modu yansısı, sorgu parametresi olmadan da tanınabilir: birincil kimliğe 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 kullanılmadığında yanıt
değişmez. Filtreler, çağıranın zaten gördüğü kataloğu daraltır (önce API anahtarı izinleri uygulanır)
ve OpenAI tarzı `limit` / `after` sayfalandırmasından önce çalışır:

```bash
GET /v1/models?capability=vision&capability=tool_calling   # listelenen her özellik true olmalıdır
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # katalogdaki `type`; olmayan satırlar `chat` olur
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` | `context_length` ile karşılaştırılan, negatif olmayan tam sayı                                      |
| `kind`        | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video`                     |
| `q`           | 1–200 karakter                                                                                      |

Bilinmeyen bir değer veya negatif olmayan tam sayı olmayan 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ğrulama ve anahtar
başına görünürlük kurallarıyla kısa ve deterministik 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` olur 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.

### Bireysel olarak 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ı dahil olmak üzere çözümlenen
sağlayıcı ve model kullanılarak gerçekleştirilir. Bir kombinasyon gizli hedefleri atlar ve
görünür bir kardeş modeli kullanabilir; çalıştırılabilir hedef kalmadığında aynı hata kodunu
döndürür. Gizliliği kaldırma bir sonraki istekte etkili olur. Yalnızca görüntü görünürlüğü
üzerindeki geçersiz kılmalar, aynı kimliğe sahip sohbet modelini gizlemez.

Bu bireysel model ayarı,
[katalog gösterimi izin/ret listelerinden](../routing/MODEL_EXPOSURE_LIST.md) ayrıdır; bu listeler,
açık dağıtımı korurken katalog reklamını ve otomatik yönlendirme adaylarını filtreler. API anahtarı
model izinleri bağımsız olarak uygulanmaya devam eder. Varsayılan katalog ön ek modu `dual` olarak
kalır.

### Düşünmesiz model varyantları

Düşünmeyi destekleyen Claude modelleri için `/v1/models`, kimliği
`claude-3-omniroute-no-thinking/` ile başlayan bir **düşünmesiz** varyantı da duyurur:

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

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

---

## Sağlayıcı Eklenti Manifestosu

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

Bifrost, CLIProxyAPI ve gelecekteki yan işlem yönlendiricileri tarafından kullanılan JSON uyumlu sağlayıcı eklenti manifestosunu döndürür. Yanıt, TypeScript sağlayıcı kayıt defterinden oluşturulur ve OAuth istemci gizli bilgilerini, çalışma zamanı ortam çözümlemesini, yürütücü işlevlerini, istek üst bilgilerini ve hesap verilerini kasıtlı olarak dışarıda bırakır.

Bir yan işlem 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.

---

## ElevenLabs ses üretimi

ElevenLabs API anahtarınızla OmniRoute'ta bir `elevenlabs` sağlayıcı bağlantısı yapılandırın.
İstemciler kendi **OmniRoute** anahtarlarıyla kimlik doğrular (`Authorization: Bearer $OMNIROUTE_API_KEY`);
ağ geçidi, depolanan sağlayıcı anahtarını `xi-api-key` olarak sağlar. ElevenLabs anahtarını
asla ağ geçidi bearer token'ı olarak göndermeyin.

| Yöntem | Yol                         | Yanıt                                      | API anahtarı uç nokta kategorisi |
| ------ | --------------------------- | ------------------------------------------ | -------------------------------- |
| POST   | `/v1/sound-generation`      | Yerel ses baytları                         | `elevenlabs`                     |
| POST   | `/v1/music`                 | Yerel ses baytları                         | `music`                          |
| POST   | `/v1/music/stream`          | Akış ses baytları                          | `music`                          |
| POST   | `/v1/music/detailed`        | Yerel çok parçalı ses ve kompozisyon planı | `music`                          |
| POST   | `/v1/music/detailed/stream` | Yerel SSE meta verileri ve ses parçaları   | `music`                          |
| POST   | `/v1/music/plan`            | JSON kompozisyon planı                     | `music`                          |

Bu uç noktalar mevcut `/v1/audio/speech`, `/v1/audio/transcriptions`,
`/v1/voices`, `/v1/text-to-speech/{voiceId}` ve `/v1/speech-to-text` rotalarını tamamlar. Yerel JSON alanları
ve `output_format` ile `enable_logging` gibi sorgu parametreleri korunur.
`/v1/music/detailed` yanıtları çok parçalı sınırlarını korur; bunları çok parçalı olarak ayrıştırın.
`/v1/music/detailed/stream`, SSE olaylarında kompozisyon meta verileri ve
base64 ses parçalarıyla birlikte `text/event-stream` döndürür. Altı rotanın tümü CORS ön uç isteklerini destekler.

```bash
export OMNIROUTE_BASE_URL="http://localhost:20128"
export OMNIROUTE_API_KEY="your-omniroute-api-key"

# Kısa bir ses efekti. Süre: 0,5 ila 30 saniye.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
  --output effect.mp3

# Müzik süresi milisaniye cinsinden ifade edilir: 3000 ila 600000.
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
  --output music.mp3
```

Artımlı ses iletimi için aynı JSON gövdesiyle `/v1/music/stream` kullanın. Kompozisyon tam olarak
`prompt` veya `composition_plan` seçeneklerinden birini kabul eder; `/v1/music/plan`, `prompt`
alanını zorunlu kılar ve isteğe bağlı olarak `source_composition_plan` kabul eder. Yerel şemalar,
ek sağlayıcı alanlarını korur; böylece kompozisyon planı sürümleri ve ince ayar seçenekleri ElevenLabs'e ulaşır.

Birleşik `/v1/music/generations` uç noktası `elevenlabs/music_v1`,
`elevenlabs/music_v2` ve `elevenlabs/music_v2_5` modellerini de kabul eder. Etkin bir ElevenLabs bağlantısıyla
bu modeller müzik kataloğunda sunulur. Bu uç nokta
`{"created":...,"data":[{"b64_json":"...","format":"mp3"}]}` döndürür. `duration` alanı
saniye cinsindendir ve `music_length_ms` alanına eşlenir; açıkça belirtilen `music_length_ms` önceliklidir.
`instrumental`, `force_instrumental` alanına eşlenir; yerel alan önceliklidir.
Akış için yerel akış uç noktalarını, yalnızca bir kompozisyon planıyla yönlendirilen istekler için
yerel kompozisyon uç noktasını kullanın.

```bash
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music/generations" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"elevenlabs/music_v1","prompt":"Gentle instrumental piano","duration":10,"instrumental":true}'
```

Uç noktasına, modele, bütçeye ve bağlantıya ilişkin kısıtlamalar upstream çağrısından önce uygulanır. Yerel
rotalar, `402` plan kısıtlaması ve `429` kota sınırı dahil olmak üzere upstream durum kodlarını ve hata gövdelerini
değiştirmeden döndürür. Mevcut olduklarında `character-cost`, `song-id`, `request-id` ve `retry-after`
üst bilgileri korunur. Ücretsiz kredi bakiyesi, her müzik modeline, çıktı biçimine veya API özelliğine erişimi
garanti etmez: Her istek için yetkilendirmeye ElevenLabs karar verir.
Birleşik uç nokta, hata durum kodlarını OmniRoute'un normalleştirilmiş hata zarfında korur.

Upstream sözleşmeleri: [ses efektleri](https://elevenlabs.io/docs/api-reference/text-to-sound-effects/convert),
[müzik kompozisyonu](https://elevenlabs.io/docs/api-reference/music/compose) ve
[akış müziği ayrıntıları](https://elevenlabs.io/docs/api-reference/music/compose-detailed-stream).

---

## 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/inpaint)      |
| 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 segmentleyici (`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 diğer adı               |
| GET    | `/api/v1/vscode/{token}/models`           | OpenAI modelleri diğer adı             |
| POST   | `/api/v1/vscode/{token}/chat/completions` | OpenAI belirteçli diğer adı            |
| POST   | `/api/v1/vscode/{token}/responses`        | OpenAI Responses belirteçli diğer adı  |
| POST   | `/api/v1/vscode/{token}/api/chat`         | Ollama belirteçli diğer adı            |
| GET    | `/api/v1/vscode/{token}/api/tags`         | Ollama etiketleri belirteçli diğer adı |

Tüm POST rotaları aynı yapıyı izler: `Bearer your-api-key` + Zod tarafından doğrulanan 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, API anahtarlarını URL içinde sorgu dizesi uyumluluğu (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) veya aşağıda belgelenen özel `/api/v1/vscode/{token}/...` uç noktaları aracılığıyla da kabul eder.

```bash
# Yeniden sıralama (bulut kayıt sağlayıcısı veya "<prefix>/<model>" biçiminde OpenAI uyumlu 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 segmentleyici
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina arama (s.jina.ai; sağlayıcı diğer 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`, "en" değerini varsayılan olarak kullanır; eksik
# bir ses veya OpenAI stok ses adı (alloy, nova, …) "Adrian" değerine dönüştürülü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": "..." }
```

> **Sağlayıcı düğümlerini yeniden sırala:** `POST /v1/rerank` ayrıca `<node-prefix>/<model>` olarak adreslenen OpenAI uyumlu sağlayıcı düğümlerine (oMLX, vLLM, Infinity, bir ağ geçidinin arkasındaki TEI, …) yönlendirme yapar. Loopback 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 bilgisayar adları da (ör. `http://reranker:8080/v1` gibi bir Docker/Compose hizmet adı) uygundur. Bunlar doğrudan çağrılır; hiçbir zaman `HTTP(S)_PROXY` veya bir bağlantının sabitlenmiş proxy'si üzerinden çağrılmaz. Başka herhangi bir ana bilgisayardaki düğümler — bir LAN cihazı 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ı giden URL politikasını (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`) geçtiğinde uygundur. Bellek motorunun yeniden sıralama adımı bu rotayı loopback üzerinden çağırır; dolayısıyla aynı kural Bellek ayarlarındaki `rerankProviderModel` için de geçerlidir.
>
> **Yerel sunucu biçimleri:** Düğüm `<base>/v1/rerank` üzerinden, 404 durumunda ise `<base>/rerank` üzerinden (Infinity, TEI) çağrılır. Üst akış gövdesi hem Cohere/OpenAI yazımını (`documents`, `return_documents`) hem de TEI yazımını (`texts`, `return_text`) taşır ve üst akış yanıtı Cohere zarf biçimine normalleştirilir: TEI'nin yalın `[{index, score, text}]` yanıtı, ince ağ geçitlerinden gelen `{results: [{index, score}]}` ve Voyage tarzı `{data: [...]}` yanıtlarının 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` listelerinde tipik olarak görüldüğü üzere) düğümün `apiType` değerini devralır; bu nedenle bir `embeddings` düğümünün modelleri varsayılan olarak sohbete ayarlanmak yerine `type: "embedding"`, bir `rerank` düğümünün modelleri ise `type: "rerank"` olur. Senkronize edilen veya elle eklenen bir satırdaki açık `supportedEndpoints` değeri yine önceliklidir.

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

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

Sağlayıcı öneki eksikse otomatik olarak eklenir. Uyuşmayan modeller `400` döndürür.

---

## Files API

Toplu giriş/çıkış ve dosya amacı yüklemeleri için OpenAI uyumlu dosya uç noktası.

| Method | Path                     | Description                                                                                                          |
| ------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | Bir dosya yükle (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ı listele                                                             |
| GET    | `/v1/files/[id]`         | Bir dosyanın meta verilerini al                                                                                      |
| DELETE | `/v1/files/[id]`         | Bir dosyayı sil                                                                                                      |
| GET    | `/v1/files/[id]/content` | Ham dosya gövdesini akış olarak geri gönder                                                                          |

**Kimlik doğrulama:** Bearer API anahtarı — dosyalar `getApiKeyRequestScope` aracılığıyla API anahtarı başına kapsamlandırılır. Bir anahtar yalnızca kendi dosyalarını görür, indirir ve siler; anahtarı olmayan bir dashboard oturumu tüm örneği okur; sahibi olmayan bir dosyaya (anonim veya dashboard oturumu yüklemesi) oturum dışındaki hiçbir çağıran erişemez. `GET /v1/files`, `REQUIRE_API_KEY=false` olsa bile anonim çağıranı — ve çözümlenemeyen bir anahtar sunan çağıranı — her kiracının dosyalarını listelemek yerine `401` ile reddeder (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

OpenAI uyumlu toplu işleme.

| Method | Path                      | Description                                                                                                              |
| ------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| POST   | `/v1/batches`             | Toplu iş oluştur — gövde, `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) tarafından doğrulanır |
| GET    | `/v1/batches`             | Toplu işleri listele                                                                                                     |
| GET    | `/v1/batches/[id]`        | Toplu iş durumunu ve `request_counts` değerini al                                                                        |
| DELETE | `/v1/batches/[id]`        | Tamamlanmış/başarısız bir toplu işi sil                                                                                  |
| POST   | `/v1/batches/[id]/cancel` | Devam eden bir toplu işi iptal et                                                                                        |

**Kimlik doğrulama:** Bearer API anahtarı. Toplu işler, dosyalarla aynı üç yönlü kural kapsamında API anahtarı başına kapsamlandırılır: yalnızca kendi anahtarı, dashboard oturumu için örnek genelinde erişim, sahibi null olan kayıtların oturum dışındaki tüm çağıranlara reddedilmesi (alma, silme, iptal ve oluşturma sırasında `input_file_id` denetimi). `GET /v1/batches`, `REQUIRE_API_KEY=false` olsa bile anonim çağıranı `401` ile reddeder.

---

## API

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

| Yöntem | Yol                    | Tanım                                                                                                        |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------------------ |
| GET    | `/v1/search`           | Yapılandırılmış arama sağlayıcılarının + yeteneklerini listeleyin                                            |
| POST   | `/v1/search`           | `v1SearchSchema` tarafından doğrulanmış bir — gövdesi arama sorgusu çalıştırın, caching/coalescing destekler |
| GET    | `/v1/search/analytics` | Sağlayıcı başına hit/latency/cache istatistikleri                                                            |

**Yetki:** Taşıyıcı API anahtarı (`extractApiKey` + `isValidApiKey`). `enforceApiKeyPolicy` aracılığıyla uygulanan arama politikası.

**Otomatik seç:** `provider` olmadan, yapılandırılmış bağlantısı olan en ucuz sağlayıcı ilk önce çalışır ve sonraki en ucuz sağlayıcı yük devretmedir. Ücretsiz son çare sağlayıcılar (`duckduckgo-free`) yalnızca başka hiçbir şey yapılandırılmadığında kullanılır. Şirket içinde barındırılan bir SearXNG bağlantısı gerçek bir `baseUrl` (katalog varsayılanı `http://localhost:8888/search` değil) depoladığında yapılandırılmış olarak sayılır: bu durumda, SearXNG 400, 401, 403 veya 404'e yanıt vermesi de dahil olmak üzere, en ucuz anahtarlı sağlayıcı yük devretme olarak anahtarlı olanların önünde 0 $ sağlayıcı olarak sıralanır. Geçerli bir `http(s)` URL olmayan veya bir bulut meta veri adresini işaret eden bir `baseUrl` sayılmaz. Bir belirteci depolayan bir SearXNG bağlantısı, yalnızca `https://` veya geri döngü `http://` üzerinden bu şekilde sıralanır. Uzak düz `http://` üzerinden bu asla bir yük devretme değildir ve son çare olarak kalır, yalnızca başka hiçbir sağlayıcı yapılandırılmadığında veya isimle istendiğinde kullanılır, dolayısıyla bu iki durumda belirteci açık metin olarak gönderir.

### Exa ve Tavily `provider_options`

Exa ve Tavily, sağlayıcıya özel 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ürde bir anahtar bırakılır. Auth, base URL, `stream` ve `outputSchema` dahil diğer anahtarlar göz ardı edilir. Diğer sağlayıcılar tarafından kullanılan düz tuşlar (`cx`, `depth`, ...) daha önce olduğu gibi çalışır.

| sağlayıcı | Üst düzey alanlar                                                                                                                                                                                                                                                                                                                                                         | Yuvalanmış                                                                                                                                          |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Exa       | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (düz temeller), `startPublishedDate`, `endPublishedDate`                                                                                                                                                                                                 | `contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours}` varsayılan `{ text: true, highlights: true }` üzerinden birleştirildi |
| 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 kazanır: `query`, `max_results`, `filters` (domainler), `country` ve `search_type` türetilen konu. Exa'da `search_type: "news"`, `category: "news"` değerini korur. Tavily ayrıca `search_type: "finance"` (`topic: "finance"`) de kabul eder.

Firecrawl arama maliyeti, döndürülen 10 sonuçtan oluşan başlatılan blok başına, blok başına 0,002 USD (2 kredi) ve çağrı başına en az bir blok ( [Firecrawl faturalandırması](https://docs.firecrawl.dev/billing) ) olarak kaydedilir: 11 sonucun maliyeti 0,004 USD'dir.

Jenerik `time_range` artık her iki sağlayıcıya da ulaşıyor: Exa `startPublishedDate` (ISO zaman damgası) alıyor ve Tavily `start_date` (`YYYY-MM-DD`) alıyor. `provider_options` açık bir tarih, eşlenen tarihi geçersiz kılar.

Exa sonuçları `id`, `highlights` (her vurgu, yalnızca `snippet` olarak kullanılan ilki değil), `highlight_scores`, `summary`, `subpages`, `entities` ve `extras` `provider_raw` içinde tutar. Tavily sonuçları `images` ve `favicon` korur.

Bağlantı arama maliyeti, `depth` `provider_options` veya bağlantı ayarlarından gelmesine bakılmaksızın, `depth` `fast` ve `standard` için 0,005 ABD Doları ve `deep` ( [Bağlantı fiyatlandırması](https://docs.linkup.so/pages/documentation/development/pricing) ) için 0,05 ABD Doları olarak kaydedilir.

Exa `type: "lite"` (Exa 3.0) daha küçük bir alan kümesini kabul eder ve başka bir alan ayarlandığında isteğin tamamını reddeder. Lite için `additionalQueries`, `systemPrompt` ve `text` ile `highlights` dışındaki tüm `contents` tuşları çağrıdan önce bırakılır. Kullanımdan kaldırılan `subpages`, `subpageTarget`, `highlights.numSentences` ve `highlights.highlightsPerUrl` artık iletilmiyor.

Maliyet muhasebesi, Exa hariç, Exa'nın kendi fiyatlandırmasını izleyen düz kayıt `costPerQuery`: 10 sonucu kapsayan `auto` (ve eski `fast`) için çağrı başına 0,007 ABD doları veya `lite` (ve eski `instant`) için 0,004 ABD doları; Sonraki her sonuç için 0,001 ABD Doları; ve `contents.summary` ayarlandığında döndürülen sonuç başına 0,001 ABD doları. Tavily `search_depth` `basic`, `fast` ve `ultra-fast` için 1 kredi (0,008 ABD doları) ve `advanced` ( [Tavily API kredileri](https://docs.tavily.com/documentation/api-credits) ) için 2 kredi (0,016 ABD doları) olarak kaydedilmiştir. Tavily'nin gelişmiş seviyeye yükselttiği `auto_parameters: true` ile yapılan bir çağrı hâlâ 1 kredi olarak kaydediliyor.

---

## 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ın.

Parallel Extract (`parallel-search`, Parallel Search ile aynı API anahtarı) yalnızca Markdown döndürür — başka herhangi bir `format` değeri `400` hatasıyla sonuçlanır — ve içeriği 100.000 karakterle sınırlar. Hedef sayfanın kendisi çıkarılamadığında upstream bunu HTTP 200 içinde bildirir; OmniRoute bunu sabit bir mesajla `422` olarak sunar.

| Method | Path            | Description                                                                  |
| ------ | --------------- | ---------------------------------------------------------------------------- |
| POST   | `/v1/web/fetch` | Bir URL'yi getirir/tarayıp çıkarır — gövde `v1WebFetchSchema` ile doğrulanır |

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

**Kotaya duyarlı geri dönüş (#8297):** Açık bir `provider` verilmediğinde havuz
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search`) sabit öncelik sırasıyla (fill-first) taranır — hız sınırına
takılmış ancak yapılandırılmış bir sağlayıcı, isteği kısa devreye sokmak yerine
atlanır ve yeniden denenebilir/kota kaynaklı bir upstream hatası (her zaman HTTP
429; Firecrawl/Tavily/TinyFish kota türü ücretsiz katmanları için 402/403 —
Jina Reader için değil ve hiçbir zaman düz bir hatalı istek olan 400 için değil)
istek sırasında henüz denenmemiş sonraki kimlik bilgileri tanımlanmış sağlayıcıya
aktarılır. Havuzdaki tüm sağlayıcılar tükendiğinde uç nokta, önceki genel
`400` yerine `Retry-After` başlığıyla tek bir `429` döndürür. Açık bir
`provider` istendiğinde sessiz geri dönüş yapılmaz — hız sınırına takılan veya
başarısız olan açık sağlayıcı kendi hatasını gösterir (hız sınırına takılmışsa
`429`, aksi durumda upstream durumu).

---

## 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ışması sırasında Bearer API anahtarı.

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

```bash
# HTTP API ile aynı host:port (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" } ] }
```

Responses-API-over-WebSocket proxy'si **yalnızca `codex`** (ChatGPT arka ucu)
için bağlanmıştır. API/dashboard ile aynı portu, `/v1/responses`,
`/responses` ve `/api/v1/responses` yollarında dinler. İlk `response.create`
çerçevesinde dahili `codex-responses-ws` köprüsü aracılığıyla kimlik doğrulaması
yapar ve hazırlık işlemlerini gerçekleştirir, 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 olmayan modeller reddedilir**
(`codex_ws_provider_required`). Kota paylaşımı yönlendirmesi 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` dosyalarında bulunur.

**Kimlik doğrulama:** El sıkışması 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 budur).

#### Model kimliği: yalın ChatGPT kimliğini kullanın (`codex/` ön eki 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ı ön ekli kimlikleri reddeder
(`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). **Yalın** kimliği (ör. `gpt-5.5`) gönderin. OmniRoute'un
köprüsü yalnızca codex için olduğundan, tünel oluşturmadan önce yalın bir kimliği
codex modeli olarak yeniden çözümler (`resolveCodexWsModelInfo`) — yalın bir
`gpt-5.5` HTTP üzerinden normalde başka bir sağlayıcıya yönlendirilecek olsa bile.

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

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

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

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

```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
tamamlanma akışını gerçekleştirir.

---

## Kotalar ve Sorun Raporlama

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

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

### Kota oturumu kurtarma (isteğe bağlı)

Terminal kota hatasıyla (gövdesi kotanın veya kredilerin tükendiğini belirten `402`/`429`/`503`)
başarısız olan akışsız bir `POST /v1/chat/completions` veya `POST /v1/responses` isteği,
hatayı döndürmek yerine bekletilip daha sonra yeniden oynatılabilir. Çağıran, istek başına
aşağıdaki üç başlıkla bu özelliği etkinleştirir:

| Başlık                       | Değer                                              |
| ---------------------------- | -------------------------------------------------- |
| `x-omniroute-quota-recovery` | `auto`                                             |
| `x-omniroute-session`        | oturum kimliği, `[A-Za-z0-9._:-]{1,128}`           |
| `x-omniroute-recovery-turn`  | oturum içinde benzersiz dönüş kimliği (aynı kural) |

Yalnızca `stream: false` olan, araç, araç geçmişi veya `previous_response_id` içermeyen ve
`x-omniroute-connection` sabitlemesi bulunmayan dönüşler uygundur; ayrıca
`STORAGE_ENCRYPTION_KEY` ayarlanmış olmalıdır (istek en fazla 24 saat boyunca şifrelenmiş
olarak saklanır). Yanıt daha sonra `recovery.poll` ile birlikte `202` olur; yoklama için
`GET /v1/quota-recoveries/{id}` kullanılır (beklemede `202`, tamamlandığında kurtarılan
gövdeyle `200`) veya `DELETE` ile iptal edilebilir. Biletler yalnızca bunları oluşturan API
anahtarına görünür. Sonucu belirsiz olan bir yeniden oynatma, iki kez gönderilmek yerine
`needs_confirmation` durumuyla sona erer. Kaynak: `src/lib/quota/quotaSessionRecovery.ts`.

---

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

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

```bash
# Text form (the historical contract — plain text for a terminal)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# Structured form — what a UI consumes
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

Anahtarın olması gerekir**`allowUsageCommand`** etkindir (varsayılan olarak kapalıdır — kontrol panelinin API anahtarı yöneticisi bunu anahtar başına değiştirir). Bu olmadan uç nokta `403` yanıtını verir.

`?format=json` ayırt edilmiş bir şekil döndürür, böylece arayan kişi, reddedilen bir veri alanını asla okumaz. Başarı üzerine:

```jsonc
{
  "allowed": true,
  // present only when the key opted into per-key usage limits (daily/weekly/5-hour USD):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // the selected provider quota snapshot, or null when nothing is cached yet:
  "provider": { "connectionId": "…", "provider": "claude", "plan": "…", "quotas": {/* … */} },
  // every connection's snapshot, so a UI can render several providers side by side:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

Reddetme durumunda (`401` bozuk anahtar / `403` izin verilmiyor) aynı rota `{ "allowed": false, "error": { "message": "…" } }` — döndürür, mevcut ama boş bir `personal`/`provider` (anahtara izin verilir, henüz hiçbir şey öğrenilmemiştir) retten farklı bir durumdur ve yalnızca JSON formu bunları ayırt eder.

**Yetki:** arayanın `isValidApiKey` — ile doğrulanan kendi Taşıyıcı API anahtarı, bu `requireManagementAuth` arkasında kalan yönetim yüzeyi (`/api/keys/…`) değildir.

### Ham ve Kesime Göre Ayarlanmış Kota Yüzdeleri

When consuming `/api/usage/om-usage`, callers should note the distinction between the percentages presented by the **plain-text output** and the structured **JSON output**:

| Bakış açısı               | Düz metin formatı (`/api/usage/om-usage` / `@@om-usage`)                                              | JSON biçimi (`?format=json`)                                                         |
| :------------------------ | :---------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------- |
| **Çıkış alanı**           | `NN% left` (örneğin, `20% left`)                                                                      | `provider.quotas` / `providers[].quotas`                                             |
| **Ölçüm**                 | **Kesime göre ayarlanmış kullanılabilir ödenek** : kesme eşiğinin üzerinde kalan kapasite             | **Ham yukarı akış kotası** : ayarlanmamış sağlayıcı ölçümü                           |
| **Kesim ölçeklendirmesi** | Korunan rezervin `0% left` olarak okunması için `effectiveRemainingPercent()` aracılığıyla ölçeklendi | Yok (sağlayıcı tarafından bildirilen ham anlık görüntü değerleri)                    |
| **Eşik verileri**         | Görüntülenen yüzdeye dahil edildi                                                                     | Bağlantı başına (veya sunucu varsayılanlarında) `quotaWindowThresholds` saklanır     |
| **Birincil tüketici**     | Etkileşimli CLIs, terminal istemleri, insan operatörler                                               | Programatik entegrasyonlar, kontrol panelleri, analizler, faturalandırma takipçileri |

#### Kesme Ayarı Formülü

OmniRoute yukarı akış tükenmesini önlemek için proaktif kota kesintilerini destekler ( `quotaWindowThresholds` bağlantısı, sağlayıcı varsayılanları veya genel esneklik ayarları aracılığıyla yapılandırılır). Bir kota penceresinde bir kesme eşiği (örneğin, `cutoff = 25%`) etkin olduğunda, metin oluşturucu kalan ödeneği şu şekilde hesaplar:

- Eğer `remaining <= cutoff`: `0%` değerini döndürür.
- Eğer `remaining > cutoff`: `((remaining - cutoff) / (100 - cutoff)) * 100` değerini döndürür.

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

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

Bir sağlayıcı penceresi düşünün** %60 ham kullanım** (buradan** Kalan %40 ham kota** ) ve yapılandırılmış** %25 kalan kota kesintisi** eşik:

| Temsil                        | Hesaplama                                          | Geriye kalan |                Zımni Kullanılan                 |
| :---------------------------- | :------------------------------------------------- | :----------: | :---------------------------------------------: |
| **Ham JSON (`?format=json`)** | Yukarı akış 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** (eğer `100 - remaining` hesaplanıyorsa) |

- **Metin neden %20 kaldı:** Hesapta kalan %40'lık fiziksel kotanın %25'i kesinti politikasına göre ayrılır. Arayanın, yönlendirici bu bağlantıya yönlendirmeyi durdurmadan önce %75'lik kullanılabilir boşluk alanının yalnızca %15'i kalmıştır. Ölçeklendirme, bağlantı sinyallerinin (`0% left`) tam olarak yönlendirmenin sona ereceği zamanda tükenmesini sağlar.
- **JSON neden ham değerleri koruyor:** JSON verisi, tam sağlayıcı anlık görüntüsünü (`UsageSnapshot`) döndürür, böylece harici araçlar, sunucu tarafı kayıplı ölçeklendirme olmadan temel gerçek yukarı akış kullanımına ve bağlantı düzeyinde `quotaWindowThresholds` erişebilir.

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

Harici bir entegrasyon (düzenleyici eklentisi veya aracı uzantısı gibi) daha önce metin uç noktasını (`NN% left`) aldıysa ve kullanılan yüzdeyi `100 - NN` olarak hesapladıysa, `?format=json` geçiş şu anlama gelir:

- Ham JSON değerlerinin okunması yansıtacaktır** fiili yukarı akış tüketimi** (Yukarıdaki örnekte %60 kullanılmıştır).
- Entegrasyon, metin uç noktasının kullanılabilir izin semantiğini korumak isterse, bağlantı düzeyindeki geçersiz kılmalar için `quotaWindowThresholds` kullanarak istemci tarafında kalan etkin formülü değerlendirebilir.

---

## Anlamsal Ö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

Anlamsal önbellek HIT'i, yanıtı **yukarı akış çağrısı yapmadan** önbellekten sunar; bu nedenle bildirilen `X-OmniRoute-Response-Latency`, orijinal yukarı akış gecikmesinden bağımsız olarak sıfıra yakındır. Gecikmeye duyarlı istemciler (karşılaştırma, p50/p99 izleme), yanıt `X-OmniRoute-Cache-Latency` başlığını kontrol etmelidir:

| Değer       | Anlam                                                                 |
| ----------- | --------------------------------------------------------------------- |
| `synthetic` | Yanıt önbellekten sunuldu; gecikme gerçek yukarı akış süresi değildir |
| _(absent)_  | Yanıt gerçek yukarı akış çağrısından geldi                            |

### Anahtar başına önbellek atlama

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

| Değer    | Davranış                                                       |
| -------- | -------------------------------------------------------------- |
| `legacy` | Normal önbellek davranışı (varsayılan)                         |
| `bypass` | Önbellek aramasını tamamen atlar; her zaman yukarı akışa gider |

Anahtar oluşturma (`POST /api/keys`) veya güncelleme (`PATCH /api/keys/[id]`) sırasında ayarlayın:

```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
```

---

## CLIProxyAPI Yönetim Uyumluluğu

OmniRoute, kullanım panolarının Claude ve Codex abonelik limitlerini okumak için çağırdığı üç [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) yönetim uç noktasına yanıt verir (örneğin T3 Code'un `cliproxy` kullanım limiti kaynağı). İstemcinin temel URL'sini OmniRoute'a yönlendirin ve yönetim anahtarı olarak `manage` kapsamına sahip bir API anahtarı kullanın. Rotalar `/v0/management/*` ve `/api/v0/management/*` adreslerinde sunulur.

| Yöntem | Yol                          | Açıklama                                                                                                                                           |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/v0/management/auth-files`  | `{ files: [{ id, auth_index, provider, email, disabled, id_token }] }` olarak Claude ve Codex OAuth bağlantıları. Belirteç içermez                 |
| POST   | `/v0/management/api-call`    | Gövde `{ auth_index, method, url, header?, data? }`. İzin verilen tek bir isteği hesabın belirteciyle gönderir ve `{ status_code, body }` döndürür |
| POST   | `/v0/management/reset-quota` | Gövde `{ auth_index }`. Bir hesabın bağlantı bekleme süresini, model kilitlenmelerini ve Codex kapsam başına bekleme sürelerini temizler           |

- `auth_index`, OmniRoute bağlantı kimliğidir. `provider`, `claude` veya `codex` değerlerinden biridir (yalnızca OAuth bağlantıları; `anthropic` API anahtarı sağlayıcısı listelenmez). Codex için `id_token.chatgpt_account_id`, depolanan çalışma alanı kimliğidir ve `plan_type`, depolanan plandır.
- `api-call` genel amaçlı bir proxy değildir. Yalnızca Claude `GET https://api.anthropic.com/api/oauth/usage` ve Codex `GET https://chatgpt.com/backend-api/wham/usage`, `GET .../wham/rate-limit-reset-credits` ve `POST .../wham/rate-limit-reset-credits/consume` isteklerini kabul eder; bunların her biri yalnızca eşleşen sağlayıcıya ait bir hesap için geçerlidir. Diğer tüm istekler yukarı akışla iletişim kurmadan `403` döndürür. Çağıranın `Authorization` başlığı (`$TOKEN$` yer tutucusu dahil) yok sayılır: OmniRoute bağlantının erişim belirtecini ekler, süresi dolmak üzereyse önce yeniler ve yalnızca izin verilen başlıkları (`anthropic-beta`; `OpenAI-Beta`, `Originator`, `Chatgpt-Account-Id`; `Accept`, `Content-Type`) iletir. `Chatgpt-Account-Id` eksikse depolanan çalışma alanı kimliği varsayılan olarak kullanılır. İstekler 15 saniye sonra zaman aşımına uğrar ve bağlantının proxy'sini kullanır.
- `reset-quota`, terminal durumları (banned, expired, credits_exhausted) olduğu gibi bırakır. Bilinmeyen bir `auth_index`, `404` döndürür.

**Kimlik doğrulama:** Giriş devre dışı olsa bile pano oturumu veya `manage` kapsamına sahip bir API anahtarı gereklidir (yollar `ALWAYS_PROTECTED_API_PATHS` içinde yer alır). Yalnızca çıkarım için kullanılan anahtarlar `403` alır. Kaynak: `src/lib/cliproxyCompat/managementApi.ts`.

---

## Kontrol Paneli ve Yönetim

Yönetim yolları (genel auth/login hariç `/api/*` )** Olumsuz** sıradan çıkarım API anahtarları tarafından yetkilendirilir. Kimlik bilgisi aileleri, kapsamlar ve curl örnekleri: [Yönetim Kimlik Doğrulaması](../guides/MANAGEMENT-AUTH.md).

### Kimlik doğrulama

| Uç nokta                      | Yöntem   | Tanım                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/auth/login`             | POST     | Giriş yapmak                                                                                                                                                                                                                                                                                                                                                       |
| `/api/auth/logout`            | POST     | Oturumu kapat                                                                                                                                                                                                                                                                                                                                                      |
| `/api/settings/require-login` | GET/POST | Giriş durumu (GET, genel). POST şifreyi belirler / oturum açmayı değiştirir: yalnızca bir şifre mevcut olduğunda operatör tarafından kullanılabilir (kontrol paneli oturumu, yerel CLI veya oturum açma devre dışı bırakılır) — API anahtarları ve `oma_` belirteçleri `403` alır); bir kontrol paneli oturumu şifreyi değiştirmek için `currentPassword` gönderir |

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

| Uç nokta                                | Yöntem                    | Tanım                                                                                                                                                                   |
| --------------------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`                        | GET/POST                  | Sağlayıcıları listeleyin / oluşturun                                                                                                                                    |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | Bir sağlayıcıyı yönetme                                                                                                                                                 |
| `/api/providers/[id]/test`              | POST                      | Sağlayıcı bağlantısını test edin                                                                                                                                        |
| `/api/providers/[id]/models`            | GET                       | Sağlayıcı modellerini listeleyin                                                                                                                                        |
| `/api/providers/validate`               | POST                      | Sağlayıcı yapılandırmasını doğrulayın                                                                                                                                   |
| `/api/providers/bulk`                   | POST                      | ONE sağlayıcısı için API anahtarlarını toplu ekleme                                                                                                                     |
| `/api/providers/import`                 | POST                      | Ayrıştırılmış bir CSV/JSON dosyasından (#6836) heterojen bir sağlayıcı LIST içe aktarın; satır başına kısmi arıza sonuçları                                             |
| `/api/provider-nodes*`                  | Çeşitli                   | Sağlayıcı düğüm yönetimi                                                                                                                                                |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | Özel modeller ve model başına geçersiz kılmalar (ekleme, güncelleme, hide/show, silme)                                                                                  |
| `/api/provider-models/validate-and-add` | POST                      | Yönetim tarafından kimlik doğrulaması yapılan, isteğe bağlı sıkı bağlantı doğrulaması ve atomik özel model kaydı; bkz. [Model doğrulama](../guides/MODEL-VALIDATION.md) |

synced/imported modelleri için `PUT /api/provider-models`, `provider`, `modelId` ve `maxOutputTokenOverride` kabul eder: pozitif bir tam sayı, manuel çıkış belirteci sınırını ayarlar ve `null` varsayılanı geri yüklemek için bunu temizler. `GET /api/provider-models?provider=<provider>`, özel model satırı olmayan modeller de dahil olmak üzere bu değerleri `modelOutputOverrides` cinsinden döndürür. Geçersiz kılma, çalışma zamanı `max_output_tokens` yeteneğini kullanır ve modelin yeniden senkronizasyonundan sonra hayatta kalır. OpenAI uyumlu sağlayıcı sayfası aynı edit/clear kontrollerini sunar ve modelleri açık görüş desteğiyle işaretler.

Uyumlu bir sağlayıcı düğümde, yazma yolları (`POST`, `PUT`, `PATCH`, `DELETE` ve `/api/provider-models/validate-and-add`) model kimliğini çıplak yukarı akış kimliği olarak saklar: ön ekli bir listeden yapıştırılan bir kimlik, düğümün kendi önekinin herhangi bir önde gelen yığınını daraltır ve yanıtlar saklanan kimliği yansıtır. Kanonik sağlayıcıların kesikli kimlikleri (örneğin `nvidia/nemotron-…`) kelimesi kelimesine saklanır. `/v1/models` hiçbir zaman yığılmış bir `<prefix>/<prefix>/<model>` kimliği yaymaz.

Özel Sohbet Tamamlama düğümleri, açık muhakeme devre dışı bırakma işlemlerini yukarı akış arka ucuna uyarlar. Başarılı bir bağlantı testi, `/models` girişi tanınan bir `owned_by` değerini kanıtlayan her ID modeli için sohbet şablonu kontrollerini otomatik olarak seçer: `vllm`, `sglang` veya `llamacpp`. Şeffaf OpenAI uyumlu sarmalayıcılar, iç içe geçmiş bir `openai` nesnesinin içindeki orijinal model girişini koruyabilir; algılama bu tür üç zarfa kadar takip eder. Eksik, bilinmeyen veya çatışan sahipliğe sahip modeller sıradan OpenAI davranışını korur. Algılama, mevcut katalog isteğini yeniden kullanır, tamamlama belirteçleri oluşturmaz ve bağlantı uç noktası değiştiğinde geçersiz kılınır.

Bu meta verileri göstermeyen bir arka ucun davranışını sabitlemek için mevcut kısmi sağlayıcı güncellemesini kullanın API:

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

O cesedi `PUT /api/providers/<connection-id>` ile gönderin. Bu bağlamda `none` açık bir akıl yürütme çabası `chat_template_kwargs.thinking=false` ve `chat_template_kwargs.enable_thinking=false` olarak gönderilir. Açık yerel şablon değerleri, sunucu tarafı bir akıl yürütme kuralı çaba gerektirmediği sürece yetkili kalır. Bu ayar yalnızca OpenAI uyumlu özel bir bağlantı Sohbet Tamamlamaları gövdesini gönderdiğinde uygulanır; Yanıt istekleri ve sıradan sağlayıcılar yerel istek şeklini korur. Sıradan OpenAI `reasoning_effort` geçişini zorlamak için `reasoningControl` `openai` olarak ayarlayın veya otomatik algılamayı kullanmak için it/set `null` çıkarın.

Claude Code otomatik mod sınıflandırıcısı, açık akıl yürütme denetimleri içermediğinde varsayılan yerel düşüncenin devre dışı bırakılmasını ister. Algılama, Claude biçimli isteklerde model adlarını veya tamamlanma sınırlarını değil, sınıflandırıcının sistem işaretleyicisini kullanır. Açık gövde kontrolleri, desteklenen effort/thinking başlıkları, yönlendirme kuralları ve çözümlenen model çalışması mevcut önceliklerini korur. Her iki sınıflandırıcı aşaması da kendi istemlerini, tamamlanma sınırlarını, durdurma dizilerini ve gerçek yukarı akış izin kararlarını korur; ikinci aşama yine de talep edilen görünür muhakemeyi sıradan metin olarak üretebilir.

### OAuth Akışları

| Uç nokta                         | Yöntem  | Tanım                  |
| -------------------------------- | ------- | ---------------------- |
| `/api/oauth/[provider]/[action]` | Çeşitli | Sağlayıcıya özel OAuth |

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

| Uç nokta              | Yöntem   | Tanım                                 |
| --------------------- | -------- | ------------------------------------- |
| `/api/models`         | GET/PUT  | Model listesi / takma ad güncellemesi |
| `/api/models/alias`   | GET/POST | Model takma adları                    |
| `/api/models/catalog` | GET      | Sağlayıcı + türüne göre tüm modeller  |
| `/api/combos*`        | Çeşitli  | Kombinasyon yönetimi                  |
| `/api/keys*`          | Çeşitli  | API anahtar yönetimi                  |
| `/api/pricing`        | GET      | Model fiyatlandırması                 |

#### Model sınırı kaynağı

`GET /api/models?withLimits=1` (ayrıca `true`; `0`/`false` veya bunun atlanması, varsayılan veri yükünü değiştirmeden tutar) her model satırına `contextWindow`, `maxInputTokens`, `maxOutputTokens` ve bir `capsSource` nesnesi ekler. `capsSource` her bir limiti sağlayan kuralı adlandırır, böylece şaşırtıcı bir limit (örneğin 1M modelinde 128k) kökenine kadar takip edilebilir. Çözümlenen değerler yönlendirmenin kullanımlarıyla aynıdır; bayrak yalnızca alanlar ekler ve hiçbir zaman değeri değiştirmez. Diğer tüm `withLimits` değerleri `400` ile reddedilir.

| `capsSource` değeri                          | Menşei                                                                         |
| -------------------------------------------- | ------------------------------------------------------------------------------ |
| `override:context`                           | Kalıcı bağlam penceresi geçersiz kılma (`model_context_overrides`)             |
| `override:max_input` / `override:max_output` | Kalıcı `max_input_tokens` / `max_output_tokens` özelliğinin geçersiz kılınması |
| `static-authoritative:<provider>/<model>`    | Statik yetkili bağlam penceresi tablosu                                        |
| `synced:<provider>/<model>`                  | models.dev senkronize edilmiş yetenek satırı                                   |
| `registry:<provider>/<model>`                | Sağlayıcı kayıt girişi                                                         |
| `spec:<model>`                               | Statik model spesifikasyonu                                                    |
| `effort-base:` öneki                         | Efor eklenmiş bir değişkenin temel modelinden ödünç alınan satır               |
| `none`                                       | Hiçbir kaynak sınırı beyan etmiyor (değer `null`)                              |

Uygulama: `src/lib/modelCapabilities.ts` `getResolvedModelCapabilitiesWithLimitSources()` ve `src/lib/modelCapabilityLimits.ts` öncelik zincirleri.

### Kullanım ve Analiz

| Uç nokta                         | Yöntem          | Tanım                                                                                                                                                                                                                                                                                                                    |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/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üzeyindeki günlükler                                                                                                                                                                                                                                                                                              |
| `/api/usage/[connectionId]`      | GET             | Bağlantı başına kullanım                                                                                                                                                                                                                                                                                                 |
| `/api/usage/token-limits`        | GET/POST/DELETE | API anahtarı başına belirteç sınırı bütçeleri                                                                                                                                                                                                                                                                            |
| `/api/usage/model-latency-stats` | GET             | Devam eden per-provider/model gecikme toplamı (avg/p50/p95/p99, başarı oranı); filtreler: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                                |
| `/api/usage/cache-health`        | GET             | `call_logs` — write/read oranı, p50/p90/p99 yazma boyutu dağılımı, yoğun yazma konsantrasyonu, model başına bölünme ve `healthy`/`degraded`/`thrash`/`no-data` kararı üzerinden hızlı önbellek durumu özeti; 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 çıkarım anahtarına değil, yönetim yetkilendirmesine (bkz. [Yönetim Kimlik Doğrulaması](../guides/MANAGEMENT-AUTH.md) ) ihtiyaç duyar. Yalnızca değiştirmek istediğiniz alanları gönderin; bunların hiçbiri olmayan bir istek `No valid fields to update` ile reddedilir. Kabul edilen alanlar `src/shared/validation/schemas/keys.ts` `updateKeyPermissionsSchema` ile tanımlanır.

| Alan                                        | Tip                                                                      | Notlar                                                                                                                                                                                                                                                                                                        |
| ------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | dize, 1-200 karakter                                                     |                                                                                                                                                                                                                                                                                                               |
| `isActive`                                  | boolean                                                                  |                                                                                                                                                                                                                                                                                                               |
| `isBanned`                                  | boolean                                                                  |                                                                                                                                                                                                                                                                                                               |
| `expiresAt`                                 | ISO 8601 tarihsaat veya `null`                                           | `null` vadeyi temizler                                                                                                                                                                                                                                                                                        |
| `modelAccessMode`                           | `all` \| `restricted`                                                    | Mod `all` olduğunda `allowedModels` boş olmalıdır                                                                                                                                                                                                                                                             |
| `allowedModels`, `blockedModels`            | dize dizisi, 1000'e kadar                                                |                                                                                                                                                                                                                                                                                                               |
| `allowedCombos`                             | dize dizisi, 500'e kadar                                                 | Anahtarı birleştiren kapılar arayabilir; doğrudan modeller `modelAccessMode` / `allowedModels` tabidir                                                                                                                                                                                                        |
| `connectionAccessMode`                      | `all` \| `restricted`                                                    | `allowedConnections` `restricted` olduğunda boş olmamalı ve `all` olduğunda boş olmalıdır                                                                                                                                                                                                                     |
| `allowedConnections`                        | UUIDs dizisi, 100'e kadar                                                |                                                                                                                                                                                                                                                                                                               |
| `allowAutoCombos`                           | boolean                                                                  | `false` bu anahtarla `auto/*` modellerine yönelik istekleri reddeder; asla ayarlamayan tuşlara izin verilir                                                                                                                                                                                                   |
| `catalogScope`                              | `all` \| `combos` \| `models`                                            | Bu anahtar için `GET /v1/models` listelediği şeyler (yalnızca kombinasyonlar, yalnızca modeller veya her ikisi); anahtarın neyi arayabileceğini değiştirmez                                                                                                                                                   |
| `forcedModel`                               | 300 karaktere kadar dize veya `null`                                     | Sohbet isteklerini `X-Route-Model` ve `body.model` üzerinden bu model/combo yönlendirir; anahtarın sınırları hala geçerlidir                                                                                                                                                                                  |
| `noLog`, `autoResolve`                      | boolean                                                                  |                                                                                                                                                                                                                                                                                                               |
| `throttleDelayMs`                           | tamsayı, 0-300000                                                        |                                                                                                                                                                                                                                                                                                               |
| `maxSessions`                               | tamsayı, 0-10000                                                         |                                                                                                                                                                                                                                                                                                               |
| `rateLimits`                                | `{ limit, window }` dizisi (pozitif tamsayılar, en fazla 50) veya `null` | `null` sınırları temizler                                                                                                                                                                                                                                                                                     |
| `accessSchedule`                            | zamanlama nesnesi veya `null`                                            | `null` programı temizler                                                                                                                                                                                                                                                                                      |
| `scopes`                                    | dize dizisi, en fazla 32                                                 |                                                                                                                                                                                                                                                                                                               |
| `allowedEndpoints`                          | dize dizisi, en fazla 20                                                 |                                                                                                                                                                                                                                                                                                               |
| `streamDefaultMode`                         | `legacy` \| `json`                                                       |                                                                                                                                                                                                                                                                                                               |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                                     | Bkz. [Anahtar başına önbellek atlama](#per-key-cache-bypass)                                                                                                                                                                                                                                                  |
| `compressionEnabled`                        | boolean                                                                  |                                                                                                                                                                                                                                                                                                               |
| `codexServiceMode`                          | Codex hizmet modlarından biri                                            |                                                                                                                                                                                                                                                                                                               |
| `disableNonPublicModels`                    | boolean                                                                  |                                                                                                                                                                                                                                                                                                               |
| `allowUsageCommand`                         | boolean                                                                  |                                                                                                                                                                                                                                                                                                               |
| `usageLimitEnabled`                         | boolean                                                                  |                                                                                                                                                                                                                                                                                                               |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | sayı >= 0 veya `null`                                                    |                                                                                                                                                                                                                                                                                                               |
| `fiveHourUsageLimitUsd`                     | sayı >= 0 veya `null`                                                    | Günlük ve haftalık limitler (`usageLimitEnabled`, `UNPRICED_USAGE_BUDGET_POLICY`) gibi uygulanan, dönüşümlü 5 saatlik USD bütçesi. `retry-after` penceredeki en eski harcamanın geçerliliğini yitirdiği zamandır ve bu, bir anahtarın sınırının çok üzerinde hâlâ engellenmiş halde kalmasına neden olabilir. |
| `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

| Uç nokta                              | Yöntem        | Tanım                                                                                                                                                                                                                                                                                                                    |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/settings`                       | GET/PUT/PATCH | Genel ayarlar. Güvenlik politikası anahtarları (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) `currentPassword` ve bir operatör kimlik bilgilerine ihtiyaç duyar — API anahtarları ve `oma_` belirteçleri `403` alır; her mutasyonun `admin` erişim belirteci kapsamına ihtiyacı vardır |
| `/api/settings/proxy`                 | GET/PUT       | Ağ proxy yapılandırması                                                                                                                                                                                                                                                                                                  |
| `/api/settings/proxy/test`            | POST          | Proxy bağlantısını test edin                                                                                                                                                                                                                                                                                             |
| `/api/settings/ip-filter`             | GET/PUT       | IP allowlist/blocklist                                                                                                                                                                                                                                                                                                   |
| `/api/settings/thinking-budget`       | GET/PUT       | Thinking/reasoning** rica etmek** yeniden yazma modu (geçiş / otomatik şerit / özel / uyarlanabilir). Sıkıştırmadan bağımsız. [THINKING_BUDGET](../guides/THINKING_BUDGET.md) bakın.                                                                                                                                     |
| `/api/settings/system-prompt`         | GET/PUT       | Küresel 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üğü yapıtlarını temizleyin                                                                                                                                                                                                                                                  |

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

| Uç nokta                               | Yöntem         | Tanım                                                                |
| -------------------------------------- | -------------- | -------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | off/lite/standard/aggressive/ultra/RTK/stacked sıkıştırmasını önizle |
| `/api/compression/language-packs`      | GET            | Mevcut Caveman dil paketlerini listeleyin                            |
| `/api/compression/rules`               | GET            | Mağara Adamı kuralı meta verilerini listeleme                        |
| `/api/context/caveman/config`          | GET/PUT        | Mağara adamına özgü ayarlar takma adı                                |
| `/api/context/rtk/config`              | GET/PUT        | Özel filtreler ve ham çıktı saklama dahil RTK'ya özgü ayarlar        |
| `/api/context/rtk/filters`             | GET            | RTK filtre kataloğu ve özel filtre tanılamaları                      |
| `/api/context/rtk/test`                | POST           | Bir metin verisine karşı RTK preview/test çalıştırın                 |
| `/api/context/rtk/raw-output/[id]`     | GET            | İşaretçi kimliğine göre tutulan, düzeltilmiş ham çıktıyı okuyun      |
| `/api/context/combos`                  | GET/POST       | Sıkıştırma kombinasyonu list/create                                  |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | Sıkıştırma kombinasyonu detail/update/delete                         |
| `/api/context/combos/[id]/assignments` | GET/PUT        | Sıkıştırma kombinasyonlarını yönlendirme kombinasyonlarına atayın    |
| `/api/context/analytics`               | GET            | Sıkıştırma analitiği takma adı                                       |

### İzleme

| Uç nokta                             | Yöntem     | Tanım                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------------------ | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | Aktif oturum takibi                                                                                                                                                                                                                                                                                                                                                                                         |
| `/api/rate-limits`                   | GET        | Hesap başına oran sınırları                                                                                                                                                                                                                                                                                                                                                                                 |
| `/api/monitoring/health`             | GET        | Durum kontrolü + sağlayıcı özeti (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). Yönetim görünümü şunları içerir: `credentialHealth`: prob önbellek skalerleri, `failedConnections` zaman `failed>0` ve `staleDbNonOkCount` (SQLite yapışkan `test_status`, gösterge değil). [MONITORING_GUIDE](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status) bakın. |
| `/api/cache/stats`                   | GET/DELETE | Önbellek istatistikleri / temizle                                                                                                                                                                                                                                                                                                                                                                           |
| `/api/modality-bridge/stats`         | GET        | Bellek içi `attempts`, başarılar/`bridged`, hatalar, önbellek isabetleri, `totalLatencyMs`, `latencySamples`, örnek cinsinden `averageLatencyMs` ve son kullanım süresi (yeniden başlatmada sıfırlama; yönetim kimlik doğrulaması)                                                                                                                                                                          |
| `/api/modality-bridge/video/runtime` | GET        | Yönetim auth/probe önce sıkı güvenilir geridöngü denetimi; sterilize edilmiş FFmpeg/ffprobe kullanılabilirliği ve sürümleri (mağazasız)                                                                                                                                                                                                                                                                     |
| `/api/modality-bridge/video/extract` | POST       | Dahili kimliği doğrulanmış güvenilir geridöngü bayt aracısı; 50 MiB girişi, sınırlı queue/32 MiB çıkışı, `503` kapasitesi, `499` bağlantı kesme, `504` son tarihi; herkese API bir yükleme değil                                                                                                                                                                                                            |

### Video karesi detayına inme

`GET /api/v1/video-bridge/drilldown` açıkça izin verilen bir Video Köprüsü isteğinden sonra `x-omniroute-video-drilldown` döndürülen, kiracıya bağlı opak bir tanıtıcıyı okur. Hem okuma hem de `DELETE` her zaman geçerli bir API anahtarı ve operatörün bağımsız `modalityBridgeVideoDrilldownRemoteEnabled` iznini gerektirir. Üretimin korunması ayrıca `modalityBridgeVideoDrilldownEnabled` ve parça başına katı `drilldown: true` gerektirir. Anahtarın boş olmayan bir uç nokta izin verilenler listesi varsa, arayanın `/v1` veya `/api/v1` kullanmasına bakılmaksızın hem GET hem de DELETE için `video` içermesi gerekir.

GET sorgusu: gerekli `handle`; isteğe bağlı `variant` (`preview`, `standard`, `detail`), `limit` (1–8; eski `frames` kabul edilir ancak `limit` ile birleştirilemez), sıfır tabanlı `page` ve `start`/`end` saniye. Her iki odak sınırı da sağlandığında `end`, `start` büyük olmalıdır. Duplicate/unknown sorgu anahtarları reddedilir. Başarılı yanıtlar `derivation`, `durationSeconds`, `frames`, `hasMore`, `page`, `variant` ve isteğe bağlı `focusWindow` içerir; mağazasız JSON Base64 dahil 32 MiB ile sınırlıdır. Büyük boyutlu çıktı 413 değerini döndürür; daha az kare isteyin.

`DELETE /api/v1/video-bridge/drilldown?handle=...` `{ "removed": 0|1 }` döndürür. Bilinmeyen, süresi dolmuş ve çapraz anahtar GETs birbirinden ayırt edilemeyen 404 yanıtlarıdır; çapraz anahtar DELETE sahibinin girişini kaldıramaz. Devre dışı bırakılan erişim 403, missing/invalid kimlik doğrulaması 401, geçersiz sorgular 400, iptal 499 ve geçici hatalar 503'ü döndürür. Tanıtıcılar süreç yereldir, on dakika sonra sona erer ve yeniden başlatmadan sağ çıkamaz. Yeni tanıtıcılar `v1.` yanı sıra 32 baytlık rastgele Base64URL jetonunu kullanır; yalnızca belirteç karmaları korunur. Eski 64-hex belirteçleri uyumluluk açısından sözdizimsel olarak okunabilir durumda kalır. İzin, kotalar ve varyant türetme ayrıntıları için [Video Köprüsü korkuluklarına](../security/GUARDRAILS.md#video-bridge-videobridgets-videobridgepipelinets) bakın.

### Yedekleme ve Export/Import

| Uç nokta                    | Yöntem | Tanım                                                                                       |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------- |
| `/api/db-backups`           | GET    | Mevcut yedeklemeleri listele                                                                |
| `/api/db-backups`           | PUT    | Manuel yedekleme oluşturma                                                                  |
| `/api/db-backups`           | POST   | Belirli bir yedekten geri yükleme                                                           |
| `/api/db-backups`           | PATCH  | Yedekleme saklama ayarlarını kaydet (yalnızca operatöre özel)                               |
| `/api/db-backups`           | DELETE | Saklanan yedeklemeleri saklama ayarlarına budama (yalnızca operatöre özel)                  |
| `/api/db-backups/export`    | GET    | Veritabanını .sqlite dosyası olarak indirin                                                 |
| `/api/db-backups/import`    | POST   | Veritabanını değiştirmek için .sqlite dosyasını yükleyin (yalnızca `?dryRun=true` doğrular) |
| `/api/db-backups/exportAll` | GET    | Tam yedeklemeyi .tar.gz arşivi olarak indirin                                               |

`/api/db-backups/export`, `/api/db-backups/exportAll` ve `/api/settings/export-json` saklanan her kimlik bilgisini dağıtır, dolayısıyla kontrol paneli oturumuna veya yerel CLI (veya oturum açmanın devre dışı bırakılmasına) ihtiyaç duyarlar. Herhangi bir kapsamın API anahtarları ve `oma_` erişim belirteçleri `403` alır. Geri yüklemeler aynı sınırı korur: `POST /api/db-backups/import` (`dryRun=true` dahil), `POST /api/db-backups` (kimliğe göre geri yükleme) ve `POST /api/settings/import-json` canlı veritabanının veya ayarların yerini alır, böylece makine kimlik bilgisi orada da `403` alır; `omniroute sync import` yerel CLI kimlik bilgisini gönderir. `DELETE /api/db-backups` (depolanan yedeklemeleri budama) ve `PATCH /api/db-backups` (saklama ayarları: kalıcı değerler, her yedeklemeden sonra otomatik budamayı yönlendirir) de aynısını yapar. Listeleme (`GET`) ve manuel yedekleme (`PUT`) oluşturma, olağan yönetim kimlik doğrulamasını korur.

### Bulut Senkronizasyonu

| Uç nokta               | Yöntem  | Tanım                          |
| ---------------------- | ------- | ------------------------------ |
| `/api/sync/cloud`      | Çeşitli | Bulut senkronizasyon işlemleri |
| `/api/sync/initialize` | POST    | Senkronizasyonu başlat         |
| `/api/cloud/*`         | Çeşitli | Bulut yönetimi                 |

### Tüneller

| Uç nokta                   | Yöntem | Tanım                                                                                      |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `/api/tunnels/cloudflared` | GET    | Kontrol paneli için Cloudflare Hızlı Tünel install/runtime durumunu okuyun                 |
| `/api/tunnels/cloudflared` | POST   | Cloudflare Hızlı Tüneli'ni (`action=enable/disable`) etkinleştirme veya devre dışı bırakma |
| `/api/tunnels/ngrok`       | GET    | Kontrol paneli için ngrok Tunnel çalışma zamanı durumunu okuyun                            |
| `/api/tunnels/ngrok`       | POST   | ngrok Tüneli'ni (`action=enable/disable`) etkinleştirme veya devre dışı bırakma            |

### CLI Araçları

| Uç nokta                           | Yöntem | Tanım                    |
| ---------------------------------- | ------ | ------------------------ |
| `/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 Temsilcileri

| Uç nokta          | Yöntem | Tanım                                                                 |
| ----------------- | ------ | --------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | Algılanan tüm aracıları (yerleşik + özel) durumla birlikte listeleyin |
| `/api/acp/agents` | POST   | Özel aracı ekleyin veya algılama önbelleğini yenileyin                |
| `/api/acp/agents` | DELETE | Özel bir aracıyı `id` sorgu parametresiyle kaldırın                   |

GET yanıtı `agents[]` (kimlik, ad, ikili dosya, sürüm, kurulu, protokol, isCustom) ve `summary` (toplam, kurulu, notFound, builtIn, özel) içerir.

### Dayanıklılık ve Hız Limitleri

| Uç nokta                          | Yöntem    | Tanım                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| --------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | Get/update istek kuyruğu, bağlantı bekleme süresi, sağlayıcı kesici ve bekleme ayarları                                                                                                                                                                                                                                                                                                                                                      |
| `/api/resilience/reset`           | POST      | Sağlayıcı devre kesicilerini sıfırlayın                                                                                                                                                                                                                                                                                                                                                                                                      |
| `/api/resilience/model-cooldowns` | GET       | Her bir (sağlayıcı, bağlantı, model) kilitlemeyi kalan süreye göre sıralanmış olarak listeleyin                                                                                                                                                                                                                                                                                                                                              |
| `/api/resilience/model-cooldowns` | DELETE    | Her şeyi silmek için bir model kilitleme — gövdesi `{provider, model}` veya `{all: true}` temizleyin                                                                                                                                                                                                                                                                                                                                         |
| `/api/rate-limits`                | GET/POST  | Hesap başına hız sınırı durumu (GET) veya bir bağlantı için geçiş hız sınırı koruması (POST `{connectionId, enabled}`). `rateLimitProtection` için desteklenen yazma yolu (hiçbir zaman `PUT /api/providers/[id]` aracılığıyla 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`) dışında bırakmaz. |
| `/api/rate-limit`                 | GET       | Küresel ücret sınırı yapılandırması (kullanımdan kaldırıldı; `/api/rate-limits` takma adı)                                                                                                                                                                                                                                                                                                                                                   |

> Dört `/api/resilience/*` yolunun tümü gerektirir** yönetim yetkilendirmesi** (`requireManagementAuth`). Sağlayıcı kesintisi, bağlantı bekleme süresi ve model kilitleme karşılaştırmasının tam bir dökümü için [Dayanıklılık (genişletilmiş)](#resilience-extended) konusuna bakın.

### Değerlendirmeler

| Uç nokta     | Yöntem   | Tanım                                                        |
| ------------ | -------- | ------------------------------------------------------------ |
| `/api/evals` | GET/POST | Değerlendirme paketlerini listele / değerlendirmeyi çalıştır |

### Politikalar

| Uç nokta        | Yöntem          | Tanım                              |
| --------------- | --------------- | ---------------------------------- |
| `/api/policies` | GET/POST/DELETE | Yönlendirme politikalarını yönetin |

### Uyumluluk

| Uç nokta                    | Yöntem | Tanım                             |
| --------------------------- | ------ | --------------------------------- |
| `/api/compliance/audit-log` | GET    | Uyumluluk denetim günlüğü (son N) |

### v1beta (İkizler Uyumlu)

| Uç nokta                   | Yöntem | Tanım                                  |
| -------------------------- | ------ | -------------------------------------- |
| `/v1beta/models`           | GET    | Modelleri Gemini formatında listeleyin |
| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` uç noktası    |

Bu uç noktalar, yerel Gemini SDK uyumluluğu bekleyen istemciler için GeminiAPI biçimini yansıtır.

### Dahili / Sistem APIs

| Uç nokta                 | Yöntem | Tanım                                                                         |
| ------------------------ | ------ | ----------------------------------------------------------------------------- |
| `/api/init`              | GET    | Arka planda senkronizasyon hizmetlerini başlatın (yönetim kimlik doğrulaması) |
| `/api/tags`              | GET    | Ollama uyumlu model etiketleri ( Ollama istemcileri için)                     |
| `/api/restart`           | POST   | Sunucunun zarif bir şekilde yeniden başlatılmasını tetikleyin                 |
| `/api/shutdown`          | POST   | Sunucunun zarif bir şekilde kapatılmasını tetikleyin                          |
| `/api/system/env/repair` | POST   | OAuth sağlayıcı ortam değişkenlerini onarın                                   |
| `/api/system/version`    | GET    | Current/latest sürümü, güncelleme durumu, yayın kanalı                        |
| `/api/system/version`    | POST   | En son sürüme dağıtıma duyarlı bir güncelleme başlatın                        |

> **Not:** Bu uç noktalar sistem tarafından dahili olarak veya Ollama istemci uyumluluğu için kullanılır. Genellikle son kullanıcılar tarafından ç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. İade:

```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 Sürüm Kanalı

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

Yalnızca geri döngü yönetim yolu (yönetici kimlik doğrulaması). Çalışan sürümü, en son yayınlanan sürümü ve otomatik güncelleme durumunu döndürür. `releaseChannel` ve `channels` toplam alanlardır (rail 3.8.54); `channel` gösterge tablosu güncelleyicisinin kullandığı dağıtım modunun (`npm`, `source` veya `docker-compose`) — korur.

```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" }
}
```

- çalışan yapının `releaseChannel` — npm kanalı: `-nightly.*` sürümleri için `nightly`, diğer ön sürümler için `next` (`-rc.*`, `-beta.*`, `-alpha.*`), `channels.latest` daha eski bir ana dalın kararlı sürümü için `lts`, aksi takdirde `latest`. Yayınlama sırasında npm dağıtım etiketini seçen `scripts/release/dist-tag.mjs` ile aynı kurallar.
- `channels` —, `npm view omniroute dist-tags` (kayıt defteri HTTP geri dönüşü) her dağıtım etiketinin yayınlanmış başlığını, `latest` ile aynı 10 dakikalık TTL ile önbelleğe alır. `latest` her zaman mevcuttur ( `latest` alanına geri döner, ardından `"unavailable"`); `next`, `nightly` ve `lts` yalnızca bu dağıtım etiketi mevcut olduğunda görünür. Bir `Cache-Control: no-cache` isteği her iki aramayı da yeniler.

Kanal modeli (4.0 GA kadar `latest` = v3, `next` = rc, `nightly` = `develop` yapıları, 4.0 GA sonra `lts` = v3 yamaları) `docs/ops/RELEASE_STRATEGY.md` 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ın transkripsiyonunu gerçekleştirin. İlk yol
segmenti yerel sağlayıcıyı seçer (`openai/…`, `deepgram/…`). Başka bir satı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`.

**Gemini Live (`gemini/gemini-3.5-transcribe-live`):** Gemini Live
WebSocket üzerinden dosya modunda transkripsiyon (bir Gemini API anahtarı gerektirir). Yükleme,
`ffmpeg` ile 16 kHz mono PCM'ye dönüştürülür (`PATH` üzerinde bulunmalıdır; dosya zaten
16 kHz mono PCM WAV ise bu gerekli değildir), oturuma aktarılır ve sonlandırılmış metin
`{ "text": "..." }` olarak döndürülür. İsteğe bağlı `language` ve `prompt` form alanları
iletilir. Sınırlar: 25 MiB üzerindeki yüklemeler veya kodu çözülmüş ses uzunluğu 10 dakikadan
fazla olan dosyalar `413` yanıtı alır; 60 saniyeden uzun süren bir dönüştürme sonlandırılır ve
`504` yanıtı döndürülür. API anahtarı yalnızca `x-goog-api-key` üstbilgisinde gönderilir,
WebSocket URL'sinde asla gönderilmez.

## 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 listesi (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 / Üst Bilgi Gerektirmeyen Takma Adlar

Bir entegrasyon `Authorization` üst bilgisi 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 biçimleri aynı kalır.
- İstemci özel üst bilgileri 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 telemetri verilerinde görünebilir. Bunları varsayılan kimlik doğrulama yöntemi 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ı için bütçe durumunu al
GET /api/usage/budget

# 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` gereklidir; `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}` biçimi `400 Bad Request` döndürür.

## Token Limitleri

API anahtarı başına **token** bütçeleri (yukarıdaki USD tabanlı Budget'tan farklıdır). İstek yolunda satır içi olarak uygulanır: bir anahtarın geçerli pencere kullanımı limitine ulaştığında istekler `429 Too Many Requests` ile reddedilir. Limitler belirli bir `model`, bir `provider` için kapsamlandırılabilir veya anahtar genelinde `global` olarak uygulanabilir; bir istekle birden fazla limit eşleştiğinde en kısıtlayıcı olan geçerli olur.

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

# Bir token limiti 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 limitini sil
DELETE /api/usage/token-limits?id=tl-abc
```

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

## İstek İşleme

1. İstemci `/v1/*` adresine istek gönderir
2. Rota işleyicisi `handleChat`, `handleEmbedding`, `handleAudioTranscription` veya `handleImageGeneration` işlevini çağırır
3. Model çözümlenir (doğrudan provider/model veya alias/combo)
4. Kimlik bilgileri, hesap kullanılabilirliği filtrelemesiyle yerel DB'den seçilir
5. Sohbet için: `handleChatCore`, anlamsal/imza önbelleğini denetler ve combo sıkıştırma ayarlarını çözümler
6. Etkin olduğunda provider çevirisinden önce proaktif sıkıştırma çalışır (`lite`, Caveman, RTK veya stacked)
7. Provider yürütücüsü üst akış isteğini gönderir
8. Yanıt istemci biçimine geri çevrilir (chat) veya olduğu gibi döndürülür (embeddings/images/audio)
9. Kullanım, sıkıştırma analitiği ve istek günlükleri kaydedilir
10. Hatalarda combo kurallarına göre geri dönüş uygulanır

Tam mimari referansı: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Combo Yönetimi

Daha üst düzey yönlendirme combo'ları (zaten `/api/combos*` altında özetlenmiştir), bir model kimliği deseninden 1:1 eşleştirilebilir; böylece OpenAI tarzı bir model kimliği şeffaf biçimde bir combo'ya yönlendirilebilir.

| Method | Path                             | Description                                                                    |
| ------ | -------------------------------- | ------------------------------------------------------------------------------ |
| GET    | `/api/model-combo-mappings`      | Tüm model→combo eşlemelerini listele                                           |
| POST   | `/api/model-combo-mappings`      | Eşleme oluştur — body: `{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ı için giden webhook abonelikleri (istek tamamlanması, kota tükenmesi, anahtar döndürme vb.).

| Method | Path                      | Açıklama                                                                  |
| ------ | ------------------------- | ------------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | Webhook'ları listeler (gizli bilgiler `<prefix>...` olarak maskelenir)    |
| POST   | `/api/webhooks`           | Webhook oluşturur — gövde: `{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | Bir webhook'u getirir                                                     |
| PUT    | `/api/webhooks/[id]`      | url/events/secret/description değerlerini günceller                       |
| DELETE | `/api/webhooks/[id]`      | Bir webhook'u kaldırır                                                    |
| POST   | `/api/webhooks/[id]/test` | Webhook URL'sine bir test yükü gönderir ve teslimat durumunu döndürür     |

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

---

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

Günlük/saatlik kotalara sahip bir arka uç sağlayıcıya/hesaba karşı API anahtarları oluşturmak ve döndürmek için otomatik anahtar yönetimi alt sistemi tarafından kullanılır.

| Method | Path                                  | Açıklama                                                                                                                                                                                                |
| ------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | Kayıtlı anahtarları listeler (yalnızca maskelenmiş önek)                                                                                                                                                |
| POST   | `/api/v1/registered-keys`             | Yeni bir kayıtlı anahtar oluşturur — gövde: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. Ham anahtarı **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 getirir (ham materyal yoktur)                                                                                                                                     |
| DELETE | `/api/v1/registered-keys/[id]`        | Kayıtlı bir anahtarı iptal eder                                                                                                                                                                         |
| POST   | `/api/v1/registered-keys/[id]/revoke` | Açık iptal uç noktası (`DELETE` ile aynı etkiyi gösterir)                                                                                                                                               |

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

---

## Aracılar Protokolü

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

| Method | Path                          | Description                                                                                                                                                       |
| ------ | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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?`) tarafından 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 — `external_id` ayarlanmışsa durumu üst akıştaki bulut aracısı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]`   | Belirtilen kimliğe sahip bir görevi siler                                                                                                                         |

> **Kimlik doğrulama:** Her yöntemde yönetim kimlik doğrulaması (`requireCloudAgentManagementAuth`) gereklidir. v3.8.0 öncesinde bu uç noktalar kimlik doğrulamasızdı — geriye dönük uyumsuz değişiklik için `588a0333` commit'ine bakın.

```bash
# Claude Code bulut görevi oluşturma
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.

| Method | Path                                         | Description                                                                                                                                                                   |
| ------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | Proxy'leri listeler (`?id=` ile bir proxy döndürür; `?id=&where_used=1` ile atama grafiğini döndürür)                                                                         |
| POST   | `/api/v1/management/proxies`                 | Proxy oluşturur — gövde `createProxyRegistrySchema` tarafından doğrulanır                                                                                                     |
| PATCH  | `/api/v1/management/proxies`                 | Proxy'yi günceller — gövde `updateProxyRegistrySchema` tarafından doğrulanır (`id` gerektirir)                                                                                |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | Proxy'yi siler (atamaları ayı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ı için etkin proxy'yi çözümlemek üzere `resolve_connection_id=<id>` parametresini iletin |
| PUT    | `/api/v1/management/proxies/assignments`     | Atama yapar — gövde `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`) tarafından doğrulanır. Dispatcher önbelleğini temizler                                            |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | Toplu atama yapar — gövde `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`) tarafından doğrulanır)                                                                |
| GET    | `/api/v1/management/proxies/health?hours=24` | Bir zaman aralığındaki toplu proxy sağlığını döndürür (başarı/başarısızlık sayıları, gecikme)                                                                                 |

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

> Görev açıklamasında belirtilen `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 kimliğe özel alt rotalar bulunmaz.

---

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

OmniRoute, birbirinden bağımsız üç geçici hata 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 depolama alanı                              | Okuma                                     | Sıfırlama / temizleme                                                       |
| ----------------------- | ------------------------------------------------- | ----------------------------------------- | --------------------------------------------------------------------------- |
| Sağlayıcı devre kesici  | `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]` | (yeniden etkinleştirme tembel olarak yapılır; sağlayıcı PUT ile temizlenir) |
| Model kilitlemesi       | Bellek içi model kullanılabilirliği kayıt defteri | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                                    |

`PATCH /api/resilience`, `providerBreaker.oauth` ve `providerBreaker.apikey` altında sağlayıcı devre kesici geçersiz kılmalarını kabul eder. Her profil `degradationThreshold`, `failureThreshold` ve `resetTimeoutMs` alanlarını destekler; aynı alanlar Dashboard → Settings → Resilience bölümünde de sunulur.

```bash
# Tek bir model kilitlemesini 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 kilitlemeleri temizle
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

Tam kavramsal referans ve devre kesici varsayılanları için [`CLAUDE.md`](../../CLAUDE.md) → "Resilience Runtime State" ve [`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md) bölümlerine bakın.

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

- **Desteklenen yazma yolu**: `POST /api/rate-limits` ile birlikte `{"connectionId": "<id>", "enabled": true|false}` gövdesi, bir bağlantı için hız sınırı korumasını açıp kapatmaya yönelik desteklenen yönetim uç noktasıdır. `PUT /api/providers/[id]`, `rateLimitProtection` değerini kasıtlı olarak değiştirmez veya tersine çevirmez (#11278).
- **`enabled: false` semantiği**: `enabled: false` ayarının yapılması, bağlantı için açıkça belirtilen korumayı kaldırır; ancak etkin bir API anahtarı bağlantısının genel otomatik etkinleştirme güvenlik ağından (`autoEnableApiKeyProviders = true`) çıkmasını **sağlamaz**. `reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`) içinde `false` ve `undefined` eşdeğerdir; açıkça koruma belirtilmemiş etkin API anahtarı bağlantıları otomatik etkinleştirme güvenlik ağı kapsamı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` (env) veya `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (Settings → Resilience / `PATCH /api/resilience`) aracılığıyla devre dışı bırakın.

---

## Yetenekler

Özel çalıştırılabilir işleyicilerle OmniRoute'u genişletmeye yönelik yetenek çerçevesi ve marketplace entegrasyonları.

| Method | Path                              | Description                                                                                                                          |
| ------ | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| GET    | `/api/skills`                     | Yüklü yetenekleri listeler — `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local` ile filtrelenebilir ve sayfalanabilir |
| GET    | `/api/skills/[id]`                | Tek bir yeteneği alır                                                                                                                |
| PUT    | `/api/skills/[id]`                | Yeteneği günceller (ad, açıklama, mod, şema, işleyici, etiketler)                                                                    |
| DELETE | `/api/skills/[id]`                | Bir yeteneği kaldırır                                                                                                                |
| POST   | `/api/skills/install`             | Ham bir manifestten yetenek yükler — gövde: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`           |
| GET    | `/api/skills/executions`          | Son yetenek çalıştırmalarını listeler (girdiler/çıktılar/süre içeren denetim izi)                                                    |
| GET    | `/api/skills/marketplace?q=...`   | SkillsMP marketplace'ten arama/popüler liste ( `skillsmpApiKey` ayarını gerektirir)                                                  |
| POST   | `/api/skills/marketplace/install` | SkillsMP'ten kimliğe göre yetenek yükler                                                                                             |
| GET    | `/api/skills/skillssh?q=&limit=`  | skills.sh kayıt defterinde arama yapar                                                                                               |
| POST   | `/api/skills/skillssh/install`    | skills.sh'ten kimliğe göre yetenek yükler                                                                                            |

**Kimlik doğrulama:** Yönetim oturumu/API anahtarı. Marketplace arama rotaları, 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.

| Method | Path                 | 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 (veritabanı bağlantısı, embeddings arka ucu, vektör dizini durumu)                           |

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

---

## MCP Sunucusu

OmniRoute, 3 aktarım türüne (stdio, SSE, streamable-http) ve kapsamlandırılmış araçlara sahip gömülü bir Model Context Protocol sunucusuyla birlikte gelir. Aşağıdaki pano uç noktaları durum/denetim verilerini okur ve HTTP aktarımlarını vekil olarak yönlendirir.

| Method | Path | Açıklama |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Kalp atışı, 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ına sahip MCP araçlarının listesi |
| GET | `/api/mcp/sse` | SSE aktarımı için açık SSE akışı (MCP devre dışıysa veya aktarım eşleşmiyorsa `503` döndürür) |
| POST | `/api/mcp/sse` | SSE aktarımında 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 iletiler) |
| POST | `/api/mcp/stream` | Streamable HTTP aktarımında 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 ( `mcp` kapsamına sahip Bearer API anahtarı) kullanır; `status`/`tools`/`audit*` rotaları panodan okunabilir (pano sunucusuna erişim dışında ek kimlik doğrulaması 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, denetim/pano kullanımı için bir A2A (Agent-to-Agent) JSON-RPC 2.0 uç noktası ve bir REST sarmalayıcısı sunar.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # OMNIROUTE_API_KEY ayarlanmadıkça 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` ile etkinleştirilir):

| Method           | Description                                                      |
| ---------------- | ---------------------------------------------------------------- |
| `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`      | `taskId` ile bir görevi getirir                                  |
| `tasks/cancel`   | `taskId` ile bir görevi iptal eder                               |

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

### Agent Card

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

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

### REST yardımcıları

| Method | Path                         | Description                                                                                                             |
| ------ | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/a2a/status`            | A2A etkinlik durumu + görev istatistikleri + önbelleğe alınmış agent 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 — `message/send` JSON-RPC çağrısı ile 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, Evals ve Assess

| Method | Path | Description |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | Bir Bearer anahtarını doğrular ve bulut eşitleme istemcileri için maskelenmiş sağlayıcı bağlantılarını ve model takma adlarını döndürür |
| POST | `/api/cloud/credentials/update` | Bulutla eşitlenen bir sağlayıcının şifrelenmiş kimlik bilgilerini günceller |
| POST | `/api/cloud/model/resolve` | Mantıksal bir model kimliğini yerel yönlendirme tablosunu kullanarak somut bir sağlayıcı/model ile çözümler |
| GET | `/api/cloud/models/alias` | Bulut eşitlemeye sunulan model takma adlarını listeler |
| GET | `/api/assess` | En son değerlendirme kategorilendirmelerini (sağlayıcı/model başına) okur |
| POST | `/api/assess` | Bir değerlendirme çalıştırır — gövde: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | Yerleşik değerlendirme paketlerini ve en son çalıştırmaları listeler |
| POST | `/api/evals` | Bir değerlendirme çalıştırmasını tetikler |
| POST | `/api/evals/suites` | Özel bir değerlendirme paketi oluşturur — gövde `evalSuiteSaveSchema` tarafından doğrulanır |
| GET | `/api/evals/suites/[id]` | Özel bir değerlendirme paketini getirir |

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

---

## ACP (Agent Client Protocol) Yönetimi

alt süreçler olarak. Bu uç noktalar ACP aracısı algılama ve özel aracı
kaydını yönetir.

| Yöntem | Yol               | Açıklama                                                                                                                                                             |
| ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | Kurulum durumu, sürüm ve ikili dosya bilgileriyle bilinen tüm CLI aracılarını (yerleşik + özel) listeler                                                             |
| POST   | `/api/acp/agents` | Özel bir ACP aracısını 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 (dashboard `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.

---

## Analiz ve Gözlemlenebilirlik

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

### Otomatik yönlendirme analizi

| Yöntem | Yol                                  | Açıklama                                                                                                                           |
| ------ | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/auto-routing`        | Toplu otomatik yönlendirme istatistikleri: toplam çağrı sayısı, strateji dağılımı, katman dağılımı, en çok kullanılan sağlayıcılar |
| GET    | `/api/analytics/auto-routing?days=7` | Zaman aralığına göre istatistikler (varsayılan 24 saat)                                                                            |

**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 analizi

| Yöntem | Yol                          | Açıklama                                                                                           |
| ------ | ---------------------------- | -------------------------------------------------------------------------------------------------- |
| GET    | `/api/analytics/compression` | Toplu sıkıştırma istatistikleri: kaydedilen belirteçler, tasarruf %, kip 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 accounts for 40% of traffic — consider diversifying"]
}
```

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

---

## Yönetici İşlemleri

Yalnızca yöneticilere özel operasyonel yönetim uç noktaları.

| Yöntem | Yol                      | Açıklama                                                                                                |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | Mevcut eşzamanlılık sınırlarını okuyun (genel + sağlayıcı başına)                                       |
| POST   | `/api/admin/concurrency` | Eşzamanlılık sınırlarını güncelleyin — 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ı yönetin (antigravity, commandCode,
devin-cli vb.). Tam liste için [Sağlayıcı Referansı](./PROVIDER_REFERENCE.md) bölümüne bakın.

| Yöntem | Yol                                     | Açıklama                                                                                                                                                                            |
| ------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cli-tools/all-statuses`           | Tüm CLI araçlarının durumu (yüklü, sürüm, son görülme)                                                                                                                              |
| GET    | `/api/cli-tools/status`                 | Bir CLI aracı için durum ayrıntısı (`?tool=` sorgusu)                                                                                                                               |
| POST   | `/api/cli-tools/apply`                  | Bir aracın oluşturulan yapılandırmasını yazar (`dryRun` önizleme yapar; kapsayıcılaştırıldığında `422` + `containerEphemeralTarget`; `migration` eski bir Codex YAML'sini 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övdede `{tool, backupId}` ile aynı uç nokta kullanıldığında 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'nin özel GPT'lerine benzer, ancak aracılar için).

| Yöntem | Yol                          | Açıklama                                                                                       |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | Tüm aracı becerilerini listeler (yerleşik + özel)                                              |
| GET    | `/api/agent-skills/[id]`     | Belirli bir aracı becerisini getirir                                                           |
| POST   | `/api/agent-skills`          | Özel bir aracı becerisi oluşturur — gövde: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | Özel bir aracı becerisini günceller                                                            |
| DELETE | `/api/agent-skills/[id]`     | Özel bir aracı becerisini siler                                                                |
| GET    | `/api/agent-skills/[id]/raw` | Ham istemi + meta verileri getirir (yürütme yok)                                               |
| POST   | `/api/agent-skills/generate` | Doğal dildeki bir açıklamadan yapay zekâ ile yeni bir beceri oluşturur                         |

**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.

| Method | Path                   | Description                                                                                                                 |
| ------ | ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | Önbelleğe genel bakış: toplam giriş sayısı, isabet oranı, diskteki boyut                                                    |
| GET    | `/api/cache/entries`   | Önbelleğe alınmış girişleri listele (sayfalandırma ile)                                                                     |
| DELETE | `/api/cache/entries`   | Önbellek girişlerini 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ği durumu (akıl yürütme yeniden oynatımı için)                                                          |
| DELETE | `/api/cache/reasoning` | Akıl yürütme önbelleğini temizle — sorgu parametreleri: `?toolCallId=<id>` (tek), `?provider=<p>` veya parametre yok (tümü) |

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

---

## Bellek Sistemi

Kalıcı belleği yönetin (FTS5 + vektör yerleştirmeleri).

| Method | Path               | Description                                                                 |
| ------ | ------------------ | --------------------------------------------------------------------------- |
| GET    | `/api/memory`      | Bellek girişlerini listele (kapsam, tür ve arama sorgusuna göre filtrele)   |
| POST   | `/api/memory`      | Yeni bir bellek girişi oluştur — gövde: `{scope, type, content, metadata?}` |
| GET    | `/api/memory/[id]` | Belirli bir bellek girişini al                                              |
| PUT    | `/api/memory/[id]` | Bir bellek girişini güncelle                                                |
| DELETE | `/api/memory/[id]` | Bir bellek girişini sil                                                     |
| GET    | `/api/memory?q=`   | Bellekte ara (FTS5 + vektör) — istatistikler aynı yanıtın içinde yer alır   |

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

---

## Webhook'lar

Olaylar için webhook aboneliklerini yönetin.

| Method | Path                            | Description                                                                |
| ------ | ------------------------------- | -------------------------------------------------------------------------- |
| 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 al                                         |
| 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 için 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.

Tam olay türleri için [Webhooks Framework](../frameworks/WEBHOOKS.md) bölümüne bakın.

---

## Beceriler Çerçevesi

Becerileri yönetin (aracı tabanlı genişletilebilirlik çerçevesi).

| Method | Path                     | Description                                                                                                       |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | Yüklü tüm becerileri listeler (yerleşik + özel)                                                                   |
| POST   | `/api/skills/install`    | Yerel bir yoldan veya URL'den beceri yükler                                                                       |
| DELETE | `/api/skills/[id]`       | Bir beceriyi kaldırır                                                                                             |
| PUT    | `/api/skills/[id]`       | Bir beceriyi etkinleştirir veya devre dışı bırakır — gövde: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | Bir beceriyi yürütür — gövde: `{skillName, apiKeyId, input?, sessionId?}`                                         |
| GET    | `/api/skills/executions` | Tüm beceriler için yürütme geçmişini listeler (`?apiKeyId=` ile filtrelenebilir)                                  |

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

Ayrıntılar için [Skills Framework](../frameworks/SKILLS.md) bölümüne bakın.

---

## Eklentiler

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

| Method | Path                               | Description                        |
| ------ | ---------------------------------- | ---------------------------------- |
| GET    | `/api/plugins`                     | Yüklü eklentileri listeler         |
| POST   | `/api/plugins/marketplace/install` | Marketplace'ten bir eklenti yükler |
| DELETE | `/api/plugins/[name]`              | Bir eklentiyi kaldırır             |
| POST   | `/api/plugins/[name]/activate`     | Bir eklentiyi etkinleştirir        |
| POST   | `/api/plugins/[name]/deactivate`   | Bir eklentiyi devre dışı bırakır   |
| GET    | `/api/plugins/[name]/config`       | Eklenti yapılandırmasını alır      |
| PUT    | `/api/plugins/[name]/config`       | Eklenti yapılandırmasını günceller |

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

Ayrıntılar için [Plugins Framework](../frameworks/PLUGIN_SDK.md) bölümüne 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** — combo yönlendirmesi üzerinden yapılandırılır ([Auto-Combo](../routing/AUTO-COMBO.md) bölümüne bakın). Combo başına karşılaştırma metrikleri `GET /api/combos/metrics` tarafından sunulur.

---

## Korumalar

Çalışma zamanı korumalarını inceleyin (PII algılama, istem enjeksiyonu algılama, görüntü köprüleme). Korumalar her istekte çalışır; çağrı başına devre dışı bırakma işlemi `x-omniroute-disabled-guardrails` istek üst bilgisi aracılığıyla yapılır — kalıcı bir etkinleştirme/devre dışı bırakma arayüzü yoktur.

| Method | Path                   | Description                                                                                                          |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/guardrails`      | Kayıtlı korumaları ve durumlarını listeler (ad / etkin / öncelik)                                                    |
| POST   | `/api/guardrails/test` | Örnek bir girdi üzerinde çağrı öncesi işlem hattını deneme amaçlı çalıştırır — gövde: `{input, disabledGuardrails?}` |

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

Ayrıntılar için [Security > Guardrails](../security/GUARDRAILS.md) bölümüne bakın.

---

---

## Kimlik Doğrulama

Dört kimlik bilgisi ailesi (dashboard oturumu, yerel CLI belirteci, `oma_live_…` Erişim Belirteci, manage kapsamlı API anahtarı) ve bunların inference anahtarlarından farkları için [Management Authentication](../guides/MANAGEMENT-AUTH.md) sayfasına bakın.

- Dashboard rotaları (`/dashboard/*`), `auth_token` çerezini kullanır
- Oturum açma işleminde kayıtlı parola karması kullanılır; yedek olarak `INITIAL_PASSWORD` kullanılır
- `requireLogin`, `/api/settings/require-login` üzerinden etkinleştirilip devre dışı bırakılabilir
- `/v1/*` rotaları, `REQUIRE_API_KEY=true` olduğunda isteğe bağlı olarak Bearer API anahtarı gerektirir
- Bu başvurudaki "management token" / "management-scoped API key", bu kılavuzda açıklanan ailelerden biri anlamına gelir; tanımlanmamış ek bir gizli bilgi türü anlamına gelmez

> **Breaking change (v3.8.0)** — `/api/v1/agents/tasks/*` ve cooldown yönetimi uç noktaları artık **management auth** (dashboard `auth_token` çerezi veya manage kapsamlı bir API anahtarı) gerektiriyor. Bu rotaları daha önce kimlik doğrulaması olmadan çağıran istemciler `401 Unauthorized` yanıtı alacak. `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`) commit'ine bakın.