# API Reference (עברית)

🌐 **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) · 🇮🇳 [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) · 🇹🇷 [tr](../../../tr/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)

---

🌐 **שפות:** 🇺🇸 [אנגלית](./API_REFERENCE.md) | 🇪🇹 [אמהרית](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [ערבית](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [אזרית](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [בולגרית](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [בנגלית](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [בוסנית](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [צ׳כית](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [דנית](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [גרמנית](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [יוונית](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [ספרדית](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [אסטונית](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [פרסית](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [פינית](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [צרפתית](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [אירית](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [גוג׳ראטית](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [האוסה](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [הינדי](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [קרואטית](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [הונגרית](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [ארמנית](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [אינדונזית](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [איגבו](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [איטלקית](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [יפנית](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [גאורגית](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [חמרית](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [קנאדה](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [קוריאנית](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [ליטאית](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [לטבית](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [מלאיאלאם](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [מראטהית](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [מלאית](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [מלטית](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [בורמזית](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [נפאלית](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [הולנדית](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [נורווגית](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [אודיה](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [פנג׳אבית](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [פיליפינית](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [פולנית](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [פורטוגזית (פורטוגל)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [פורטוגזית (ברזיל)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [רומנית](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [רוסית](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [סינהלית](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [סלובקית](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [סלובנית](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [סרבית](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [שוודית](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [סווהילית](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [טמילית](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [טלוגו](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [תאית](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [טורקית](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [אוקראינית](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [אורדו](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [אוזבקית](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [וייטנאמית](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [יורובה](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [סינית (מפושטת)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [סינית (מסורתית)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

תיעוד הליבה של OmniRoute API. הוא מכסה את הממשק הציבורי `/v1` ואת נקודות הקצה הנפוצות ביותר לניהול; הקובץ הקריא למכונה [`docs/openapi.yaml`](../openapi.yaml) ועץ הנתיבים תחת `src/app/api/` הם המקורות המקיפים.

לפרוטוקול הממוקד התואם ל-OpenAI ולמטריצת היכולות של הספקים, ראו
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md).

---

## תוכן עניינים

- [השלמות צ'אט](#chat-completions)
- [חכירות בלעדיות של הפעלות מנוהלות](#exclusive-managed-session-leases)
- [הטמעות](#embeddings)
- [יצירת תמונות](#image-generation)
- [OCR למסמכים](#document-ocr)
- [רשימת מודלים](#list-models)
- [מניפסט תוסף ספק](#provider-plugin-manifest)
- [נקודות קצה לתאימות](#compatibility-endpoints)
- [API לקבצים](#files-api)
- [API לאצוות](#batches-api)
- [API לחיפוש](#search-api)
- [הזרמה באמצעות WebSocket](#websocket-streaming)
- [דיווח על מכסות ובעיות](#quotas--issues-reporting)
- [מטמון סמנטי](#semantic-cache)
- [לוח בקרה וניהול](#dashboard--management)
- [ניהול קומבינציות](#combo-management)
- [Webhooks](#webhooks)
- [מפתחות רשומים (ניהול אוטומטי)](#registered-keys-auto-management)
- [פרוטוקול סוכנים](#agents-protocol)
- [שרתי Proxy לניהול](#management-proxies)
- [עמידות (מורחבת)](#resilience-extended)
- [מיומנויות](#skills)
- [זיכרון](#memory)
- [שרת MCP](#mcp-server)
- [שרת A2A](#a2a-server)
- [ענן, הערכות ואומדן](#cloud-evals--assess)
- [עיבוד בקשות](#request-processing)
- [אימות](#authentication)

---

## השלמות צ'אט

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

### כותרות מותאמות אישית

| כותרת                    | כיוון | תיאור                                                                                                                                                                                      |
| ------------------------ | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `X-OmniRoute-No-Cache`   | בקשה  | יש להגדיר כ־`true` כדי לעקוף את המטמון                                                                                                                                                     |
| `x-omniroute-no-memory`  | בקשה  | יש להגדיר כ־`true` כדי לדלג על הזרקת זיכרון ומיומנויות עבור בקשה זו (משקף מצב ללא מטמון; מונע את תקורת האסימונים/העלות לכל קריאה)                                                          |
| `X-OmniRoute-Progress`   | בקשה  | יש להגדיר כ־`true` עבור אירועי התקדמות                                                                                                                                                     |
| `X-Session-Id`           | בקשה  | מפתח הפעלה דביקה לצורך שיוך הפעלות חיצוני                                                                                                                                                  |
| `x_session_id`           | בקשה  | מתקבלת גם גרסה עם קו תחתון (HTTP ישיר)                                                                                                                                                     |
| `X-OmniRoute-Session-Id` | בקשה  | תג הפעלה/שיחה שסופק על ידי מבצע הקריאה (מזין גם את הזיכרון). כאשר הוא קיים, הוא נשמר כפי שהוא ב־`call_logs.session_tag` לצורך שיוך עלויות לפי הפעלה (#8249) — לעולם אינו נוצר כאשר הוא חסר |
| `Idempotency-Key`        | בקשה  | מפתח מניעת כפילויות (חלון של 5 שניות)                                                                                                                                                      |
| `X-Request-Id`           | בקשה  | מפתח חלופי למניעת כפילויות                                                                                                                                                                 |
| `x-omniroute-connection` | בקשה  | קיבוע בקשה למודל יחיד לחיבור ספק (חשבון) אחד לפי המזהה שלו — ראו [קיבוע חשבון לכל בקשה](#account-pinning-per-request)                                                                      |
| `X-OmniRoute-Cache`      | תגובה | `HIT` או `MISS` (ללא הזרמה)                                                                                                                                                                |
| `X-OmniRoute-Idempotent` | תגובה | `true` אם כפילויות הוסרו                                                                                                                                                                   |
| `X-OmniRoute-Progress`   | תגובה | `enabled` אם מעקב ההתקדמות פעיל                                                                                                                                                            |
| `X-OmniRoute-Session-Id` | תגובה | מזהה ההפעלה בפועל שבו OmniRoute השתמש                                                                                                                                                      |
| `X-OmniRoute-Request-Id` | תגובה | מזהה מתאם של הבקשה (כאשר הוא ידוע)                                                                                                                                                         |
| `X-OmniRoute-Version`    | תגובה | גרסת הבנייה של OmniRoute (קיימת תמיד)                                                                                                                                                      |
| `X-OmniRoute-Cost-Saved` | תגובה | הסכום בדולר ארה"ב שנחסך באמצעות המטמון במקרה של `HIT` (פגיעות מטמון בלבד)                                                                                                                  |
| `X-OmniRoute-Decision`   | תגובה | נתיב הניתוב: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` הוא אסטרטגיית השילוב, או `single` עבור בקשה שאינה משולבת) — קיים תמיד בתגובות השלמה                             |

> הערה לגבי Nginx: אם אתם מסתמכים על כותרות עם קווים תחתונים (לדוגמה `x_session_id`), הפעילו את `underscores_in_headers on;`.

#### קיבוע חשבון לכל בקשה

כאשר לספק יש כמה חיבורים (חשבונות או מפתחות), OmniRoute בדרך כלל בוחר אחד
באמצעות אסטרטגיית בחירת החשבון שלו. במקום זאת, בקשה יכולה לקבע חיבור מסוים אחד
באמצעות הכותרת `x-omniroute-connection`:

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

- **היכן למצוא את המזהה.** פתחו את דף הספק בלוח הבקרה
  (**לוח הבקרה → ספקים → <provider>**) ולחצו על תגית המזהה `xxxxxxxx…` בשורת חיבור —
  פעולה זו מעתיקה את מזהה החיבור המלא.
- **אילו בקשות מכבדות אותו.** בקשות למודל יחיד (`provider/model`) בנקודות הקצה
  `/v1/chat/completions`,‏ `/v1/messages` ו-`/v1/responses`. שילובים מתעלמים מהכותרת: במקום זאת,
  הצמידו חשבון לכל שלב בשילוב באמצעות החיבור של השלב עצמו.
- **ההצמדה מחייבת, ואינה רק העדפה.** נעשה שימוש בלעדי בחיבור המוצמד. כשל
  בתוך הבקשה מתעד את תקופת הצינון של החשבון, אך **אינו** עובר לחשבון מקביל
  של אותו ספק.
- **תקופת צינון ומכסה משחררות את ההצמדה.** בזמן שהחיבור המוצמד נמצא בתקופת צינון,
  מיצה את המכסה או נחסם בידי מדיניות מכסה, בקשות מאוחרות יותר חוזרות לחיבורים
  האחרים של הספק, בדיוק כמו תעבורה שאינה מוצמדת.
- **מזהים לא מוכרים או מושבתים גורמים לכשל.** מזהה שאינו נמצא במאגר הפעיל של הספק (נמחק,
  הושבת או שייך לספק אחר) אינו מותיר חשבון כשיר, ולכן הבקשה
  נכשלת במקום להיות מנותבת בשקט ליעד אחר.

Claude Code שולח כותרות מותאמות אישית באמצעות `ANTHROPIC_CUSTOM_HEADERS`. הוסיפו אותו לבלוק `env`
בקובץ `~/.claude/settings.json`, או בקובץ `.claude/settings.json` ברמת הפרויקט כדי להצמיד חשבון
שונה לכל פרויקט:

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

מקור: `src/sse/handlers/chat.ts` (קריאת הכותרת), `src/sse/services/auth.ts` ו-
`src/sse/services/sessionAffinityPin.ts` (שחרור ההצמדה ובדיקת ההיעדרות מהמאגר).

> **כותרות טלמטריית עלויות:** תגובות הצלחה שאינן מוזרמות כוללות גם את ערכת טלמטריית העלויות `X-OmniRoute-*` —‏ `X-OmniRoute-Response-Cost` (בדולר ארה״ב, עם 10 ספרות קבועות אחרי הנקודה; `0.0000000000` עבור שימוש חינמי/ללא תמחור), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`,‏ `X-OmniRoute-Model`,‏ `X-OmniRoute-Provider`,‏ `X-OmniRoute-Latency-Ms`,‏ `X-OmniRoute-Cache-Hit` ו-`X-OmniRoute-Fallback-Attempts` (רק כאשר > 0), וכן `X-OmniRoute-Request-Id` ו-`X-OmniRoute-Version`. כותרות אלה מופקות על ידי השלמות צ׳אט, `/v1/responses`,‏ `/v1/messages`, **וגם נקודות הקצה למדיה** —‏ `/v1/embeddings`,‏ `/v1/images/generations`,‏ `/v1/audio/speech`,‏ `/v1/audio/transcriptions`,‏ `/v1/rerank`,‏ `/v1/videos/generations`,‏ `/v1/music/generations` ו-`/v1/moderations` (העלות תמיד `0`). עלות המדיה מחושבת לפי סוג המדיה (לכל תמונה, לכל שנייה, לכל תו, לכל יחידת חיפוש) כאשר תמחור זמין; אחרת היא `0` (פתוח במקרה כשל).

> **סמנטיקת עלות בפגיעה במטמון:** בפגיעה במטמון הסמנטי (`X-OmniRoute-Cache-Hit: true`) לא מתבצעת קריאה לשירות במעלה הזרם, ולכן `X-OmniRoute-Response-Cost` הוא `0.0000000000` (העלות **המצטברת** של אספקת הפגיעה). העלות המקורית/זו שהייתה צפויה מדווחת בנפרד ב-`X-OmniRoute-Cost-Saved`. צרכני נתוני חיוב צריכים לסכום את `X-OmniRoute-Response-Cost` (פגיעות אינן עולות דבר); כלי ניתוח של המטמון יכולים לצבור את `X-OmniRoute-Cost-Saved`.

## חכירות סשן מנוהלות בלעדיות

חכירת סשן מנוהלת בלעדית היא חוזה ניתוב אופציונלי, ניטרלי ללקוח: בעלים פעיל אחד מחזיק חיבור OmniRoute כשיר אחד. היא אינה חוכרת מודל, דורשת OAuth, מזהה לקוח מסוים, או דורשת ספק מסוים.

מפתח ה-API המאמת חייב להיות בעל היקף `lease:exclusive` ורשימת `allowedConnections` מפורשת שאינה ריקה. גבול שינוי מסד הנתונים אוכף את שני השדות יחד ביצירת מפתח ובעדכונים חלקיים.

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

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

תגובות מוצלחות של רכישה, חידוש ושחרור חושפות חותמות זמן, `state`, ו-`generation` חיובי מדויק, אך לעולם לא את החיבור או האישורים שנבחרו. חידוש ושחרור מספקים את ה-generation בגוף ה-JSON:

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

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

בעל חכירה פעיל יכול לבקש במפורש מטא-נתונים תצוגתיים בטוחים לפרטיות עבור הקישור הנוכחי שלו:

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

פעולת סטטוס אופציונלית זו מגודרת על ידי הבעלים האוטם, מפתח ה-API המנוהל המאומת, וה-generation הפעיל המדויק בעסקת מסד נתונים אחת. `displayName` הוא רק שם החיבור המוגדר המקוצר; הוא `null` כאשר אין שם מוגדר בטוח. OmniRoute לעולם אינו מחליף כתובת אימייל או זהות חשבון שנוצרה. ערך הספק הוא תווית תצוגה לא רגישה ולעולם אינו מזהה ספק תואם שנוצר. אישורים, אסימונים, קובצי Cookie, מזהי חיבור גולמיים או מזהי מפתח API, גיבובי בעלים, סודות גידור ונתוני ניתוב פנימיים אינם נכללים.

חיפושים עם מפתח שגוי, בעלים שגוי, generation מיושן, חסר, פג תוקף, משוחרר ולא חוקי, כולם מחזירים את אותה שגיאת `409 LEASE_FENCE_STALE` ללא מטא-נתונים של חיבור. לקוח שקיבל את תגובת ההמתנה לקיבולת אינו בעל קישור פעיל לבדיקה. כאשר הניתוב מעביר חכירה פעילה, אותו generation נשאר תקף והסטטוס מחזיר באופן אטומי את הקישור החדש, לעולם לא את הישן. לקוחות קיימים נשארים ללא שינוי מכיוון שתגובות רכישה, חידוש, שחרור והמתנה שומרות על צורותיהן הקודמות.

חוזה שרת זה אינו משנה את `/status` הסטנדרטי של OpenAI Codex. Codex הסטנדרטי מדווח כעת על ספק המודל שלו ומצב האימות/חשבון המובנה אך אינו מציג מטא-נתונים שרירותיים של חשבון ספק מותאם אישית; אינטגרציה מאוחרת יותר של הלקוח חייבת לקרוא לפעולה זו ולהחליט כיצד להציג את `connection.displayName`.

כל בקשת הסקה מנוהלת מספקת אז את שני כותרות הבקרה:

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

הבעלים המדויק, ה-generation, החיבור הפעיל ומפתח ה-API המאומת מגודרים מיד לפני כל ניסיון במעלה הזרם הנתמך. הפעלה חוזרת של בעלים ו-generation עם מפתח אחר נכשלת גם כאשר מפתח זה מאפשר את אותו חיבור. בעלים גולמיים אינם נשמרים, נרשמים, נשמרים בתמונת המצב של הבקשה, או מועברים במעלה הזרם.

תחרות זמנית מחזירה HTTP `429` עם `Retry-After` ו:

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

תגובה זו פירושה רק שקבוצת הזכאים הרגילה לא הייתה ריקה וכל מועמד פנוי הוחזק על ידי חכירה פעילה זרה. מודלים/ספקים לא נתמכים, אי התאמה במדיניות, צינון, מכסה, תקינות וכשלים אחרים של זכאות רגילה שומרים על תגובות OmniRoute הקיימות שלהם.

### `x-omniroute-compression`

עקיפה לכל בקשה של תוכנית הדחיסה. בעדיפות הגבוהה ביותר — גוברת על עקיפת שילוב הניתוב, הפרופיל הפעיל, ההפעלה האוטומטית והברירת מחדל של הפאנל. ערכים:

| ערך           | השפעה                                                                                  |
| ------------- | -------------------------------------------------------------------------------------- |
| `off`         | אין דחיסה עבור בקשה זו.                                                                |
| `default`     | פרופיל ברירת המחדל הנגזר מהפאנל (מתעלם מהפרופיל הפעיל). מנועים עם אובדן נשארים כבויים. |
| `safe`        | הסרת כפילויות וקיפול רווחים בלבד.                                                      |
| `allow-lossy` | שמור את תוכנית המפעיל עבור בקשה זו, כולל סיכומים ושכתובים של סגנון.                    |
| `engine:<id>` | מנוע יחיד כאשר מופעל, לדוגמה `engine:rtk`. הצטרפות לכל בקשה עבור מנוע זה.              |
| `<combo>`     | שילוב בעל שם, מתאים לפי שם (לא תלוי רישיות) תחילה, ואז לפי מזהה.                       |

הערות:

- ערכים לא ידועים מתעלמים (הבקשה לעולם אינה נדחית); הרזולוציה עוברת לעדיפות המפעיל הרגילה.
- אם מספר שילובים חולקים שם, העבר את **מזהה** השילוב להתאמה דטרמיניסטית.
- שילוב ששמו הוא `off` או `default` לא ניתן לבחור לפי שם (מילות מפתח אלו מתפרשות תחילה); הפנה לשילוב כזה לפי מזההו.
- מתג הדחיסה הראשי הוא שער קשיח: כאשר הדחיסה מושבתת גלובלית, כותרת זו אינה יכולה להפעיל אותה.

התוכנית המיושמת מוחזרת בכותרת התגובה:

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

כאשר `<source>` הוא אחד מ-`request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, או `off`.

---

## הטמעות

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

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

ספקים זמינים: Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI.

מזהי הקטלוג הם בתבנית `provider/model` (לדוגמה: `jina-ai/jina-embeddings-v5-omni-small`). גם מזהי מודלים של Jina ללא שם הספק שמופיעים ברישום (לדוגמה `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) מזוהים. פעולות ההטמעה/הדירוג מחדש/הסיווג/הפילוח של Jina משתמשות תחילה בפרטי הגישה `jina-ai` מלוח הבקרה; נעשה שימוש ב-`JINA_AI_API_KEY` כחלופה רק כאשר לא קיים מפתח בלוח הבקרה. הכרטיס `jina-reader` מיועד ל-Reader / `r.jina.ai` בלבד (`POST /v1/web/fetch`) ולעולם אינו מספק הטמעות או דירוג מחדש.

מודלים ברישום שמצהירים על תמיכה מולטימודלית מקבלים גם עד 32 פריטים מובְנים שאינם תלויים בספק.
סוגי פריטי המדיה הם `text`, `image`, `audio`, `video` ו-`document`. ה-`source` של המדיה
הוא `{"type":"url","url":"https://..."}` או
`{"type":"base64","data":"...","media_type":"..."}`.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
וכינוי המשפחה `jina-ai/jina-embeddings-v5-omni` → omni-small) מקבל גם מסמכי
EmbeddingsV5Request מקוריים של Jina ו**מעביר אותם ללא שינוי** אל `https://api.jina.ai/v1/embeddings`:

```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,..." }]
    }
  ]
}
```

ערכי `{ image | audio | video | pdf }` מקוריים יכולים להיות כתובת URL ציבורית מסוג HTTPS, כתובת URI מסוג `data:`, או
base64 גולמי. OmniRoute אינו ממיר אובייקטים אלה למחרוזות ואינו מושך כתובות URL מקוריות של תמונות — Jina מאחזר
את המדיה הציבורית בעצמו. שדות נוספים של Jina (`task`, `normalized`, `truncate`, `embedding_type`)
מועברים הלאה. יחידות SKU של Jina המיועדות לטקסט בלבד עדיין דוחות מסמכים שאינם טקסט.

מגבלות אבטחה ותעבורה:

- כתובות URL של מדיה מרוחקת חייבות להיות ציבוריות ומסוג HTTPS. פריטי `{type,source:url}` קנוניים נמשכים
  בצד השרת (אימות מחדש של הפניות, זמן קצוב, מגבלות גודל, DNS ציבורי וקיבוע חיבור) ומוטמעים
  לפני הקריאה לספק. פריטי `{image:"https://..."}` מקוריים של Jina מועברים כפי שהם
  לאחר אותה בדיקת HTTPS ציבורי; Jina מושך את כתובת ה-URL.
- מדיית base64 מוטבעת מוגבלת ל-8 MiB לאחר פענוח לכל פריט ול-16 MiB לאחר פענוח בכל הבקשה.

תרגום עבור ספקים (פריטים קנוניים לעולם אינם מועברים ללא שינוי):

- מודלים מולטימודליים של Jina: כל פריט ברמה העליונה הופך לאובייקט אחד עם מפתח לפי סוג המדיה
  (`text` / `image` / `audio` / `video` / `pdf`), תוך שימוש בכתובות URI מסוג data עבור מדיה מוטבעת; וקטור אחד לכל
  פריט ברמה העליונה.
- משפחת Gemini Embedding 2: מערך אחד ברמה העליונה הופך לבקשה מקורית יחידה מסוג
  `models/{model}:embedContent` עם `content.parts` (`text` או `inline_data`).
- llama.cpp (`llama-cpp/<model>`, כל מודל שהשרת המקומי טען): פריטי `text` קנוניים
  הופכים למחרוזות רגילות, ו-`image` / `audio` / `video` הופכים כל אחד לאובייקט
  `{"content": [part]}` אחד, באמצעות חלקי תוכן הצ'אט של llama-server (`image_url`,
  `input_audio` עם הפורמט `wav` / `mp3` / `flac`, ו-`input_video`) עם נתונים מוטבעים; וקטור אחד
  לכל פריט ברמה העליונה. השרת חייב לפעול עם `--embedding --mmproj …`; ללא מקרן הוא
  דוחה את המדיה בעצמו. `document` אינו נתמך.
- מודלים לא מוכרים/דינמיים ללא מטא-נתונים מפורשים של סוגי מדיה דוחים קלט מובנה עם HTTP 400.

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

שילובים לא נתמכים של מודל/סוג מדיה מחזירים HTTP 400 במקום לכפות המרה על הפריט. שדות הרחבה שאינם שדות קלט
בבקשות מחרוזת/אסימון מדור קודם ממשיכים לעבור ללא שינוי.

```bash
# הצגת כל מודלי ההטמעה
GET /v1/embeddings
```

---

## יצירת תמונות

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

{
  "model": "openai/gpt-image-2",
  "prompt": "שקיעה יפה מעל הרים",
  "size": "1024x1024"
}
```

הספקים הזמינים כוללים את OpenAI (GPT Image 2),‏ xAI (Grok Image),‏ Together AI (FLUX),‏ Fireworks AI,‏ Nebius (FLUX),‏ Hyperbolic,‏ NanoBanana,‏ **OpenRouter**,‏ **ZenMux**,‏ SD WebUI (מקומי),‏ ComfyUI (מקומי).

`n` מחזיר `n` תמונות בתוך `data[]`. עבור ספקים שה-API שלהם במעלה הזרם מחזיר תמונה אחת בכל קריאה
(Black Forest Labs,‏ Stability AI,‏ Leonardo,‏ Ideogram,‏ Haiper,‏ Hyperbolic,‏ Magnific/Freepik,
‏NVIDIA NIM,‏ Cloudflare Workers AI), מתבצעות `n` קריאות נפרדות במעלה הזרם, עם עד 4 קריאות פעילות במקביל. ערך
`seed` קבוע מוסט לפי אינדקס הקריאה (`seed`,‏ `seed + 1`, …), כך שהתמונות שונות אך נותרות
ניתנות לשחזור. `n` מוגבל ל-10. הבקשה כולה נכשלת אם אחת מהקריאות נכשלת. רשימת
הפורמטים להפצה מקבילית היא `SINGLE_IMAGE_FANOUT_FORMATS` בקובץ
`open-sse/handlers/imageGeneration/fanOut.ts`.

ZenMux משתמש מחדש בחיבור הקיים עם מפתח ה-API ומקבל את התחיליות `zenmux/` או `zm/`:

- `zenmux/openai/gpt-image-2` משתמש ב-OpenAI Images API של ZenMux. האפשרויות כוללות את `size`,
  `quality`,‏ `n`,‏ `output_format`,‏ `output_compression`,‏ `background` ו-`response_format`.
- מפרסמים אחרים, כגון `zm/meta/muse-image-1.0`, משתמשים בנקודת הקצה `:predict` של Vertex AI מבית ZenMux.
  ‏`n` ממופה אל `sampleCount`,‏ `aspect_ratio` אל `aspectRatio`, ו-`image_size`
  (`1K`,‏ `2K`,‏ `4K`) אל `sampleImageSize`. ערך `size` בפיקסלים מספק יחס גובה-רוחב בלבד,
  ולא ממדי פיקסלים מובטחים. היחסים, הרזולוציות והכמויות הנתמכים משתנים בהתאם למודל.
- `zm/inclusionai/ming-image-0.1-design` בוחר את הממדים שלו בעצמו. יש להשמיט את `size`,
  `aspect_ratio` ו-`image_size`; ערכים מפורשים מחזירים HTTP 400. ניתן לבקש PNG,‏ JPEG ו-WebP
  באמצעות `output_format`.

שילוב זה תומך ביצירת תמונות מטקסט, ולא בעריכת תמונות ייחוס. הפלט של Vertex
מנורמל אל `data[].b64_json`;‏ `response_format: "url"` מחזיר כתובת URL מסוג HTTPS ממעלה הזרם
או כתובת URL של נתוני base64 כאשר זמינים רק בתים של התמונה. פלטים ריקים או מסוננים
מחזירים שגיאה במקום הצלחה ריקה. הגישה למודלים תלויה בחשבון ZenMux.
ראו [Vertex API של ZenMux](https://docs.zenmux.ai/api/vertexai/generate-images) ואת
[OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image).

```bash
# הצגת כל מודלי התמונות
GET /v1/images/generations
```

---

## OCR למסמכים

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

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

`model` בוחר את ספק ה-OCR באמצעות קידומת `provider/model`; מזהה מודל ללא קידומת (למשל
`mistral-ocr-latest`) משויך לספק הרשום שלו, ואם `model` מושמט, ברירת המחדל היא
Mistral (`mistral-ocr-latest`). ספקים רשומים (`open-sse/config/ocrRegistry.ts`):

| מזהה ספק                      | מזהה מודל            | ערך `model`                                                       | הערות                                                                                           |
| ----------------------------- | -------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (או `mistral-ocr-latest` ללא קידומת) | סינכרוני — התגובה מוחזרת ישירות מקריאת ה-upstream היחידה.                                       |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                       | upstream אסינכרוני (`analyze` + תשאול) — ראו להלן.                                              |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                           | סינכרוני, דרך נקודת הקצה לשותפים `openapi/chat/completions` של Vertex AI — פרטי אימות/URL להלן. |

כל שלושת הספקים מגיבים באותו מבנה גוף בסגנון Mistral:

```json
{
  "pages": [{ "index": 0, "markdown": "# טקסט שחולץ..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}
```

### תהליך התשאול של Azure Document Intelligence

ה-API מסוג `analyze` של Azure Document Intelligence הוא אסינכרוני: הבקשה הראשונית מחזירה כותרת
`Operation-Location` במקום גוף, ויש לתשאל לקבלת התוצאה. המטפל
(`open-sse/handlers/ocr.ts`) מתשאל את כתובת ה-URL הזו בכל שנייה, עד 30 ניסיונות, נכשל מיד (ולא
ממשיך לתשאל) כאשר תגובת התשאול אינה `ok` או כאשר הסטטוס הוא `"failed"`, ומחזיר `504` אם
הפעולה עדיין פועלת לאחר שמכסת הניסיונות מוצתה. תגובת Azure הסופית מנורמלת לאותו מבנה
`pages`/`markdown` שבו משתמש Mistral לפני שהיא מוחזרת למבצע הקריאה, כך שקוד הלקוח אינו צריך
לטפל בספק באופן מיוחד.

### אימות ופתרון נקודת קצה עבור Vertex AI DeepSeek OCR

`vertex-deepseek-ocr` משתמש מחדש באותו אימות של Vertex AI שבו OmniRoute כבר תומך עבור
תעבורת צ'אט/תמונות (`open-sse/executors/vertex.ts`): מפתח ה-API של החיבור הוא אישור JSON מסוג
Service Account (שמוחלף באסימון גישה קצר־חיים של OAuth באמצעות תהליך JWT-bearer)
או אסימון גישה של OAuth שכבר הונפק ונעשה בו שימוש כפי שהוא. כתובת ה-URL של נקודת הקצה ב-upstream היא
נקודת הקצה הכללית לשותפים `openapi/chat/completions` של Vertex, שנבנית מהפרויקט ומהאזור
של החיבור — ערך מפורש של `providerSpecificData.project`/`providerSpecificData.region` תמיד גובר;
אחרת, הפרויקט נגזר מהערך `project_id` שב-JSON של ה-Service Account, וברירת המחדל של האזור
היא `us-central1`. שני הפתרונות מתבצעים ב-`open-sse/handlers/ocr.ts`
(`resolveVertexOcrAccessToken`,‏ `resolveVertexOcrBaseUrl`), ונצרכים על ידי
`src/app/api/v1/ocr/route.ts` לפני ההעברה אל `handleOcr`.

---

## רשימת מודלים

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

→ מחזיר את כל מודלי הצ'אט, ההטמעה והתמונות + שילובים בפורמט OpenAI
```

### קידומות מזהי מודלים (`?prefix=`)

רוב המודלים מוצגים תחת **קידומת ספק**. הקידומת שתקבלו נקבעת באמצעות דגל התכונה
`MODELS_CATALOG_PREFIX_MODE`, וניתן לעקוף אותה **עבור כל בקשה בנפרד** באמצעות פרמטר
שאילתה — שימושי עבור לקוח שמעוניין ברשימה נקייה מבלי לשנות את ההגדרה הכללית בשרת
עבור כל השאר:

```bash
GET /v1/models?prefix=alias        # מזהה אחד לכל מודל — קידומת הכינוי הקצרה
GET /v1/models?prefix=dual         # שתי הצורות (ברירת המחדל של השרת)
GET /v1/models?prefix=canonical    # רק קידומת מזהה הספק המלאה
```

| מצב         | פלט                                                       | הערות                                                                                                                                                     |
| ----------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **וגם** `claude/claude-sonnet-4-6` | **ברירת המחדל.** שני המזהים מנותבים לאותו מודל; נשמרו כדי שתצורות לקוח שבהן אחת מהצורות הוגדרה בקוד ימשיכו לפעול. מכפיל בקירוב את גודל הקטלוג.            |
| `alias`     | `cc/claude-sonnet-4-6`                                    | רשומה אחת לכל מודל. ספקים ללא כינוי נפרד עדיין פולטים את הרשומה שלהם, כך שדבר אינו אובד.                                                                  |
| `canonical` | `claude/claude-sonnet-4-6`                                | רשומה אחת לכל מודל תחת קידומת מזהה הספק המלאה. ספקים ללא כינוי נפרד (למשל `antigravity/…`, `agy/…`) פולטים גם כאן את המזהה היחיד שלהם, כך שדבר אינו אובד. |

ניתן לזהות שיקוף במצב `dual` גם ללא פרמטר השאילתה: הוא מכיל שדה `parent`
המצביע אל המזהה הראשי.

לקוחות שמציגים בורר מודלים צריכים לבקש `?prefix=alias` — זה מה שעושה
[תוסף OmniCopilot עבור VS Code](../guides/VSCODE-COPILOT.md).

### מסנני גילוי (`?capability=`, `?min_context=`, `?kind=`, `?q=`)

`GET /v1/models` מקבל מסנני גילוי אופציונליים. ללא אף אחד מהם, התגובה
אינה משתנה. הם מצמצמים את הקטלוג שהקורא כבר יכול לראות (הרשאות מפתח ה-API מוחלות תחילה),
והם מופעלים לפני הדפדוף בסגנון OpenAI באמצעות `limit` / `after`:

```bash
GET /v1/models?capability=vision&capability=tool_calling   # כל יכולת שמופיעה ברשימה חייבת להיות true
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # ערך `type` בקטלוג; שורות ללא ערך כזה הן `chat`
GET /v1/models?q=sonnet&limit=10                           # התאמה שאינה תלוית רישיות לפי מזהה או שם
```

| פרמטר         | ערכים                                                                                               |
| ------------- | --------------------------------------------------------------------------------------------------- |
| `capability`  | `attachment`, `reasoning`, `structured_output`, `temperature`, `thinking`, `tool_calling`, `vision` |
| `min_context` | מספר שלם שאינו שלילי, המושווה ל-`context_length`                                                    |
| `kind`        | `chat`, `audio`, `embedding`, `image`, `moderation`, `music`, `rerank`, `video`                     |
| `q`           | 1–200 תווים                                                                                         |

ערך לא מוכר, או `min_context` שאינו מספר שלם שאינו שלילי (לדוגמה `1.5`),
מחזיר HTTP `400`, וההודעה מפרטת את הערכים החוקיים. מימוש:
`src/app/api/v1/models/catalogFilters.ts`.

### רשימה מצומצמת של מודלים (`POST /v1/models/query`)

`POST /v1/models/query` מחזיר רשימה קצרה ודטרמיניסטית מאותו קטלוג, עם אותן
הרשאות ואותה נראות לכל מפתח כמו `GET /v1/models`:

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

כל שדה הוא אופציונלי. `capabilities` ו-`exclude` מקבלים מערך או מחרוזת המופרדת בפסיקים;
`max_output` מושווה ל-`max_output_tokens`. התוצאות ממוינות תחילה לפי `owned_by`, ולאחר מכן לפי `id`.
ערך ברירת המחדל של `limit` הוא `20`, וערכים מעל `100` מוגבלים ל-`100`. JSON לא תקין, שדה לא מוכר
או ערך לא חוקי מחזירים HTTP `400`.

### מודלי צ'אט מוסתרים בנפרד

מודל שמסומן כ-**מוסתר** בדף הספק שלו אינו נכלל בקטלוג ונדחה
עם HTTP `404` / `model_not_found` כאשר מבקשים אותו במפורש. הבדיקה משתמשת בספק
ובמודל לאחר הפענוח, לרבות כינויי ספקים, קידומות צמתים של ספקים תואמים וברירות מחדל
של חיבורים. שילוב מדלג על יעדים מוסתרים ויכול להשתמש באפשרות גלויה מאותה קבוצה; כאשר לא
נותר יעד בר-הרצה, מוחזר אותו קוד שגיאה. ביטול ההסתרה נכנס לתוקף בבקשה
הבאה. עקיפות נראות לתמונות בלבד אינן מסתירות את מודל הצ'אט בעל אותו מזהה.

הגדרת מודל פרטנית זו נפרדת מ-
[רשימות ההתרה/חסימה לחשיפת מודלים](../routing/MODEL_EXPOSURE_LIST.md), שמסננות את פרסום הקטלוג
ואת המועמדים לניתוב אוטומטי, תוך שמירה על שיגור מפורש. הרשאות מודלים של מפתחות API
ממשיכות לחול באופן עצמאי. מצב קידומת הקטלוג המוגדר כברירת מחדל נשאר `dual`.

### וריאנטים של מודלים ללא חשיבה

עבור מודלי Claude בעלי יכולת חשיבה, `/v1/models` מפרסם גם וריאנט **ללא חשיבה** שמזההו מתחיל בקידומת `claude-3-omniroute-no-thinking/`:

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

בחירת מזהה זה (למשל, בתצורת Claude Code שתמיד מצרפת בלוק `thinking`) מפנה בחזרה אל `<provider>/<model>` האמיתי כאשר ההסקה מושבתת — באמצעות `thinking:{type:"disabled"}` בנתיב `/v1/messages`, או באמצעות השמטת השדות `reasoning`/`reasoning_effort` בנתיב `/v1/chat/completions`. הווריאנט מופיע רק עבור מודלים ממשפחת Claude שתומכים בחשיבה **וגם** מכבדים את `disabled` (כך, למשל, מודלים אדפטיביים בלבד שדוחים את `disabled` אינם נכללים). מפעילים יכולים לאלץ את הפעלת הווריאנט או את השבתתו עבור כל מודל באמצעות `ModelSpec.noThinkingAlias`.

---

## מניפסט תוסף ספק

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

מחזיר את מניפסט תוספי הספקים הבטוח לשימוש ב-JSON, המשמש את Bifrost, את CLIProxyAPI ואת
נתבי ה-sidecar העתידיים. התגובה נוצרת ממרשם הספקים של TypeScript
ומחריגה במכוון סודות לקוח של OAuth, פתרון משתני סביבת זמן ריצה,
פונקציות הפעלה, כותרות בקשה ונתוני חשבון.

השתמשו בנקודת קצה זו כאשר sidecar פועל מחוץ לתהליך ואינו יכול לייבא ישירות את
`open-sse/config/providerPluginManifestRegistry.ts`.

---

## נקודות קצה לתאימות

| שיטה | נתיב                                      | פורמט                             |
| ---- | ----------------------------------------- | --------------------------------- |
| 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 (עריכה/השלמת תמונה) |
| POST | `/v1/videos/generations`                  | יצירת וידאו בסגנון OpenAI         |
| POST | `/v1/music/generations`                   | יצירת מוזיקה בסגנון OpenAI        |
| POST | `/v1/audio/transcriptions`                | OpenAI Audio (המרת דיבור לטקסט)   |
| POST | `/v1/audio/speech`                        | OpenAI TTS (מחזיר גוף שמע)        |
| POST | `/v1/rerank`                              | דירוג מחדש בסגנון Cohere/Voyage   |
| POST | `/v1/classify`                            | סיווג של Jina (`api.jina.ai`)     |
| POST | `/v1/segment`                             | מפלח של Jina (`segment.jina.ai`)  |
| POST | `/v1/moderations`                         | OpenAI Moderations                |
| GET  | `/v1/models`                              | OpenAI                            |
| POST | `/v1/models/query`                        | רשימה מצומצמת ומסוננת של מודלים   |
| 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               |
| GET  | `/api/v1/vscode/{token}/models`           | כינוי למודלים של OpenAI           |
| POST | `/api/v1/vscode/{token}/chat/completions` | כינוי OpenAI עם אסימון            |
| POST | `/api/v1/vscode/{token}/responses`        | כינוי OpenAI Responses עם אסימון  |
| POST | `/api/v1/vscode/{token}/api/chat`         | כינוי Ollama עם אסימון            |
| GET  | `/api/v1/vscode/{token}/api/tags`         | כינוי לתגיות Ollama עם אסימון     |

כל נתיבי POST פועלים באותו מבנה: `Bearer your-api-key` + גוף JSON המאומת באמצעות Zod (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema` וכו'; ראו `src/shared/validation/schemas.ts`). במקרה של כשל באימות הסכימה מוחזר 4xx.

עבור לקוחות שאינם יכולים לצרף `Authorization: Bearer ...`, OmniRoute מקבל גם מפתחות API בכתובת ה-URL, באמצעות תאימות למחרוזת שאילתה (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) או באמצעות נקודות הקצה הייעודיות `/api/v1/vscode/{token}/...` המתועדות להלן.

```bash
# דירוג מחדש (ספק ממרשם הענן, או צומת ספק תואם OpenAI בתבנית "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# סיווג Jina (פרטי גישה ל-Foundation API)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# מפלח Jina
POST /v1/segment     { "content": "...", "return_chunks": true }

# חיפוש Jina‏ (s.jina.ai; כינויי ספק: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# ניהול תוכן
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — מחזיר גוף audio/mpeg (או בפורמט המבוקש)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS דורש שפה וקול: ברירת המחדל של `language` היא "en"; קול חסר
# או שם קול מובנה של OpenAI‏ (alloy, nova, …) מוחלף ב-"Adrian"
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# עריכת תמונה (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# יצירת וידאו / מוזיקה (מזהה מודל עם קידומת ספק)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **צומתי ספק לדירוג מחדש:** `POST /v1/rerank` מנתב גם לצומתי ספק תואמי OpenAI
> (oMLX, vLLM, Infinity, ‏TEI מאחורי שער, …) שאליהם פונים בתבנית `<node-prefix>/<model>`. צומתי
> לולאה חוזרת (`localhost`, `127.0.0.1`, `172.16.0.0/12`) תמיד כשירים, וכך גם שמות מארחים
> שהמפעיל מציין ב-`OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` (לדוגמה, שם שירות של Docker/Compose כגון
> `http://reranker:8080/v1`; הפנייה אליהם מתבצעת ישירות, לעולם לא דרך `HTTP(S)_PROXY` או דרך
> ה-proxy המקובע של חיבור). צמתים בכל מארח אחר
> — מחשב ברשת LAN או עמית Tailscale — כשירים רק כאשר המפעיל מפעיל את דגל היכולת
> `RERANK_REMOTE_PROVIDER_NODES` **וגם** כתובת ה-URL הבסיסית של הצומת עומדת במדיניות כתובות ה-URL היוצאות
> של הספק (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`).
> שלב הדירוג מחדש של מנוע הזיכרון קורא לנתיב זה דרך
> לולאה חוזרת, ולכן אותו כלל חל על `rerankProviderModel` בהגדרות הזיכרון.
>
> **תצורות שרת מקומי:** הקריאה לצומת מתבצעת ב-`<base>/v1/rerank`, ובמקרה של 404, ב-`<base>/rerank`
> (Infinity, TEI). גוף הבקשה לשירות במעלה הזרם כולל הן את האיות של Cohere/OpenAI (`documents`,
> `return_documents`) והן את האיות של TEI (`texts`, `return_text`), והתגובה ממעלה הזרם
> מנורמלת למעטפת של Cohere: המערך החשוף של TEI ‏`[{index, score, text}]`, המבנה `{results: [{index, score}]}`
> משערים דקים והמבנה בסגנון Voyage ‏`{data: [...]}` — כולם מוחזרים ללקוח בתור
> `{results: [{index, relevance_score, document?}]}`, ממוינים לפי ציון ומוגבלים ל-`top_n`.

> **גילוי צומתי ספק:** מודלים בצומת ספק תואם OpenAI מופיעים ב-`GET /v1/models`
> תחת קידומת הצומת. שורות שאינן כוללות מטא-נתונים של נקודות קצה (כמקובל ברשימות `/v1/models` מקומיות)
> יורשות את ה-`apiType` של הצומת, כך שהמודלים של צומת `embeddings` הם `type: "embedding"` והמודלים של
> צומת `rerank` הם `type: "rerank"`, במקום שברירת המחדל שלהם תהיה צ'אט; ערך `supportedEndpoints` מפורש
> בשורה מסונכרנת או בשורה שנוספה ידנית עדיין מקבל קדימות.

### נתיבי ספק ייעודיים

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

קידומת הספק מתווספת אוטומטית אם היא חסרה. מודלים שאינם תואמים מחזירים `400`.

---

## Files API

נקודת קצה תואמת OpenAI לקבצים עבור קלט/פלט באצווה והעלאות לפי ייעוד הקובץ.

| שיטה   | נתיב                     | תיאור                                                                                                     |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/files`              | העלאת קובץ (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — עד 512 MiB |
| GET    | `/v1/files`              | הצגת רשימת הקבצים עבור מפתח ה-API המאומת                                                                  |
| GET    | `/v1/files/[id]`         | אחזור המטא-נתונים של קובץ                                                                                 |
| DELETE | `/v1/files/[id]`         | מחיקת קובץ                                                                                                |
| GET    | `/v1/files/[id]/content` | הזרמת גוף הקובץ הגולמי בחזרה                                                                              |

**אימות:** מפתח API מסוג Bearer — הקבצים מתוחמים לפי מפתח API באמצעות `getApiKeyRequestScope`. מפתח
רואה, מוריד ומוחק רק את הקבצים שלו; סשן לוח מחוונים ללא מפתח קורא את
המופע כולו; הגישה לקובץ ללא בעלים (העלאה אנונימית או העלאה מסשן לוח מחוונים) נדחית עבור כל
קורא שאינו בעל סשן. `GET /v1/files` דוחה קורא אנונימי — וכן מפתח שסופק אך
לא ניתן לזהותו — עם `401` גם כאשר `REQUIRE_API_KEY=false`, במקום להציג את הקבצים של
כל הדיירים (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

עיבוד אצוות תואם OpenAI.

| שיטה   | נתיב                      | תיאור                                                                                                     |
| ------ | ------------------------- | --------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | יצירת אצווה — הגוף מאומת באמצעות `v1BatchCreateSchema` (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | הצגת רשימת האצוות                                                                                         |
| GET    | `/v1/batches/[id]`        | אחזור סטטוס האצווה + `request_counts`                                                                     |
| DELETE | `/v1/batches/[id]`        | מחיקת אצווה שהסתיימה/נכשלה                                                                                |
| POST   | `/v1/batches/[id]/cancel` | ביטול אצווה הנמצאת בתהליך                                                                                 |

**אימות:** מפתח API מסוג Bearer. האצוות מתוחמות לפי מפתח API בהתאם לאותו כלל תלת-מצבי כמו
הקבצים: מפתח הבעלים בלבד, סשן לוח מחוונים עבור המופע כולו, ורשומות ללא בעלים נדחות עבור כל
קורא שאינו בעל סשן (אחזור, מחיקה, ביטול ובדיקת `input_file_id` בעת היצירה).
`GET /v1/batches` דוחה קורא אנונימי עם `401` גם כאשר `REQUIRE_API_KEY=false`.

---

## API לחיפוש

הפשטה עבור ספקי חיפוש באינטרנט (Tavily, Brave, Exa, Serper וכו').

| שיטה | נתיב                   | תיאור                                                                                            |
| ---- | ---------------------- | ------------------------------------------------------------------------------------------------ |
| GET  | `/v1/search`           | הצגת ספקי החיפוש שהוגדרו והיכולות שלהם                                                           |
| POST | `/v1/search`           | הרצת שאילתת חיפוש — גוף הבקשה מאומת באמצעות `v1SearchSchema`, עם תמיכה בשמירה במטמון/איחוד בקשות |
| GET  | `/v1/search/analytics` | נתוני התאמות/השהיה/מטמון לפי ספק                                                                 |

**אימות:** מפתח API מסוג Bearer ‏(`extractApiKey` + `isValidApiKey`). מדיניות החיפוש נאכפת באמצעות `enforceApiKeyPolicy`.

### `provider_options` של Exa ושל Tavily

Exa ו-Tavily קוראים שדות ייחודיים לספק מתוך אובייקט בעל מרחב שמות:
`provider_options.exa` (או `provider_options["exa-search"]`) ו-`provider_options.tavily`
(או `provider_options["tavily-search"]`). רק המפתחות שלהלן מועברים. כל אחד מהם
נבדק מול סכמת Zod משלו ב-`open-sse/handlers/search/providerOptionsPassthrough.ts`,
ומפתח מסוג שגוי מושמט. כל מפתח אחר אינו נלקח בחשבון, לרבות אימות, כתובת URL בסיסית,
`stream` ו-`outputSchema`. המפתחות השטוחים המשמשים ספקים אחרים (`cx`, `depth`, ...) פועלים
כבעבר.

| ספק    | שדות ברמה העליונה                                                                                                                                                                                                                                                                                                                                                         | שדות מקוננים                                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Exa    | `type`, `category`, `userLocation`, `moderation`, `additionalQueries`, `objective`, `systemPrompt`, `compliance` (ערכים פרימיטיביים שטוחים), `startPublishedDate`, `endPublishedDate`                                                                                                                                                                                     | `contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours}` ממוזג מעל ברירת המחדל `{ text: true, highlights: true }` |
| 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` | —                                                                                                                                                               |

השדות הגנריים תמיד מקבלים עדיפות: `query`, `max_results`, `filters` (דומיינים), `country` וכן
הנושא הנגזר מ-`search_type`. ב-Exa, ‏`search_type: "news"` משמר את `category: "news"`.
Tavily מקבל גם `search_type: "finance"` ‏(`topic: "finance"`).

השדה הגנרי `time_range` מועבר כעת לשני הספקים: Exa מקבל `startPublishedDate` (חותמת זמן
בפורמט ISO), ו-Tavily מקבל `start_date` ‏(`YYYY-MM-DD`). תאריך מפורש ב-`provider_options`
דורס את התאריך שמופה.

תוצאות Exa שומרות את `id`, `highlight_scores`, `summary`, `subpages`, `entities` ואת `extras` בתוך
`provider_raw`. תוצאות Tavily שומרות את `images` ואת `favicon`.

חישוב העלויות עדיין משתמש במאגר השטוח `costPerQuery`. Tavily מחייב
יותר קרדיטים לכל קריאה כאשר `search_depth: "advanced"`, וההפרש הזה אינו משתקף
ב-`usage.search_cost_usd`.

---

## Web Fetch API

חילוץ תוכן מכתובת URL באמצעות ספק web-fetch מוגדר (Firecrawl, Jina
Reader, Tavily Extract, TinyFish Fetch, Nimble Extract, Parallel Extract).

Parallel Extract (`parallel-search`, עם אותו מפתח API כמו Parallel Search) מחזיר Markdown
בלבד — כל `format` אחר גורר שגיאת `400` — ומגביל את התוכן ל-100,000 תווים. כאשר
לא ניתן לחלץ את דף היעד עצמו, השירות במעלה הזרם מדווח על כך בתוך תגובת HTTP 200;
OmniRoute מציג זאת כשגיאת `422` עם הודעה קבועה.

| שיטה | נתיב            | תיאור                                                                 |
| ---- | --------------- | --------------------------------------------------------------------- |
| POST | `/v1/web/fetch` | אחזור/גירוד של כתובת URL — גוף הבקשה מאומת באמצעות `v1WebFetchSchema` |

**אימות:** מפתח API מסוג Bearer (`extractApiKey` + `isValidApiKey`). המדיניות נאכפת באמצעות `enforceApiKeyPolicy`.

**מעבר חלופי מודע למכסה (#8297):** כאשר לא מצוין `provider` מפורש, מתבצעת סריקה של המאגר
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search` →
`parallel-search`)
בסדר עדיפות קבוע
(מילוי הראשון תחילה) — ספק מוגדר שקצב הבקשות אליו הוגבל אינו עוצר את הבקשה אלא
מדולג, וכשל במעלה הזרם שניתן לנסות מחדש או שקשור למכסה
(HTTP 429 תמיד; 402/403 עבור מסלולים חינמיים מבוססי מכסה של Firecrawl/Tavily/TinyFish —
לא עבור Jina Reader, ולעולם לא עבור בקשה שגויה רגילה מסוג 400) גורם למעבר
לספק הבא שטרם נוסה ושיש עבורו פרטי גישה, בזמן הבקשה. כאשר כל הספקים במאגר
מוצו, נקודת הקצה מחזירה `429` יחיד (עם כותרת `Retry-After`)
במקום `400` הגנרי הקודם. כאשר מתבקש `provider` מפורש,
**אין** מעבר חלופי שקט — ספק מפורש שקצב הבקשות אליו הוגבל או שנכשל
מציג את השגיאה שלו (`429` אם קצב הבקשות הוגבל, ואחרת את סטטוס
השירות במעלה הזרם).

---

## הזרמה באמצעות WebSocket

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

מאמת לחיצת יד לשדרוג WebSocket ומחזיר הודעות לדוגמה של פרוטוקול התקשורת (`request`, `cancel`). מסגרות WS בפועל מטופלות בידי שרת ה-WS המצורף, מחוץ לטבלת הנתיבים של Next.js.

**אימות:** מפתח API מסוג Bearer במהלך לחיצת היד.

### Responses API באמצעות WebSocket (עבור codex בלבד)

```bash
# אותו מארח:פורט כמו API ה-HTTP (ברירת המחדל היא 20128); שדרגו את החיבור:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (או: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# המסגרת הראשונה חייבת להיות response.create:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

פרוקסי של Responses-API-over-WebSocket מחובר **בלעדית אל `codex`** (תשתית
ChatGPT). הוא מאזין באותו פורט כמו ה-API/לוח הבקרה בנתיבים `/v1/responses`,
`/responses` ו-`/api/v1/responses`. במסגרת `response.create` הראשונה הוא
מבצע אימות + הכנה באמצעות הגשר הפנימי `codex-responses-ws`, בוחר חיבור
OAuth של codex ויוצר מנהרה אל `wss://chatgpt.com/backend-api/codex/responses`
באמצעות תעבורת `wreq-js`. **מודלים שאינם codex נדחים** (`codex_ws_provider_required`).
לניתוב שיתוף מכסות השתמשו ב-`model: "qtSd/<group>/codex/<model>"`. המימוש נמצא ב-
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts`.

**אימות:** מפתח API מסוג Bearer במהלך לחיצת היד. שרת ה-HTTP המצורף (`server-ws.mjs`)
חייב להיות נקודת הכניסה הפעילה (וזו ברירת המחדל כאשר `app/server-ws.mjs` קיים).

#### מזהה מודל: השתמשו במזהה ChatGPT הבסיסי (ללא הקידומת `codex/`)

ה-**Codex CLI** של OpenAI מאמת את שם המודל בצד הלקוח כאשר
`supports_websockets = true` ו**דוחה מזהים עם קידומת ספק** כגון
`codex/gpt-5.5` (`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). שלחו את המזהה **הבסיסי** (למשל `gpt-5.5`). הגשר של OmniRoute
מיועד ל-codex בלבד, ולכן הוא פותר מחדש מזהה בסיסי כמודל codex
(`resolveCodexWsModelInfo`) לפני יצירת המנהרה לספק במעלה הזרם — אף שמזהה בסיסי
`gpt-5.5` היה מנותב אחרת לספק אחר באמצעות HTTP.

#### הגדרת OpenAI Codex CLI

הפנו את Codex CLI אל OmniRoute באמצעות הוספת ספק מותאם אישית עם תמיכה ב-WebSocket
אל `~/.codex/config.toml` (השתמשו ב-`CODEX_HOME` נפרד כדי להימנע משינוי
תצורה קיימת):

```toml
model = "gpt-5.5"                 # מזהה בסיסי — לא "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # ללא לוכסן מסיים; כתובת ה-WS נגזרת ממנו (השתמשו ב-https/wss בסביבת ייצור)
wire_api = "responses"                    # הערך הנתמך היחיד מאז פברואר 2026
supports_websockets = true                # מפעיל את תעבורת Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # מכיל את מפתח ה-API של OmniRoute‏ (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # מפתח API של OmniRoute‏ (כל מפתח אם REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

ה-CLI משדרג את `base_url + /responses` ל-WebSocket, ו-OmniRoute יוצר עבורו מנהרה
אל חיבור OAuth הנבחר של codex. התהליך אומת מקצה לקצה מול השרת
המקומי: ChatGPT מחזיר `codex.rate_limits` + `response.created` ומזרים את
ההשלמה.

---

## מכסות ודיווח על בעיות

| מתודה | נתיב                | תיאור                                                                        |
| ----- | ------------------- | ---------------------------------------------------------------------------- |
| GET   | `/v1/quotas/check`  | אימות מראש של המכסה עבור `provider` + `accountId` לפני הנפקת מפתח רשום       |
| POST  | `/v1/issues/report` | דיווח ל-GitHub על כשל במכסה/בהנפקת מפתח (דורש `GITHUB_ISSUES_REPO` + אסימון) |

**אימות:** מפתח API מסוג Bearer (`isAuthenticated`).

---

## שימוש בשירות עצמי (`/api/usage/om-usage`)

כל מפתח API יכול לקרוא את נתוני השימוש והמכסות **שלו עצמו** — ללא אימות ניהולי. זוהי נקודת הקצה שבה
לקוח (CLI, הפאנל של OmniCopilot) משתמש כדי להציג לבעל המפתח את ההוצאה שלו.

```bash
# תצורת טקסט (החוזה ההיסטורי — טקסט פשוט למסוף)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# תצורה מובנית — מה שממשק משתמש צורך
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"
```

במפתח חייבת להיות מופעלת האפשרות **`allowUsageCommand`** (כבויה כברירת מחדל — מנהל מפתחות ה-API
בלוח המחוונים מפעיל או מכבה אותה לכל מפתח בנפרד). בלעדיה נקודת הקצה משיבה `403`.

`?format=json` מחזיר מבנה מבחין, כך שהקורא לעולם אינו קורא שדה נתונים מתוך
סירוב. במקרה של הצלחה:

```jsonc
{
  "allowed": true,
  // קיים רק כאשר המפתח בחר להשתמש במגבלות שימוש לכל מפתח (USD יומי/שבועי):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // תמונת מצב המכסה של הספק שנבחר, או null כאשר דבר טרם נשמר במטמון:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // תמונת המצב של כל חיבור, כדי שממשק משתמש יוכל להציג כמה ספקים זה לצד זה:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

במקרה של סירוב (`401` עבור מפתח שגוי / `403` עבור חוסר הרשאה), אותו נתיב מחזיר
`{ "allowed": false, "error": { "message": "…" } }` — `personal`/`provider` שקיים אך ריק
(המפתח מורשה, אך טרם התקבל מידע) הוא מצב שונה מסירוב, ורק תצורת ה-JSON
מבחינה ביניהם.

**אימות:** מפתח ה-Bearer API של הקורא עצמו, המאומת באמצעות `isValidApiKey` — זהו _לא_
ממשק הניהול (`/api/keys/…`), שנותר מוגן באמצעות `requireManagementAuth`.

### אחוזי מכסה גולמיים לעומת אחוזים מותאמי סף הפסקה

בעת צריכת `/api/usage/om-usage`, על הקוראים לשים לב להבדל בין
האחוזים המוצגים ב**פלט הטקסט הפשוט** לבין **פלט ה-JSON** המובנה:

| היבט               | תצורת טקסט פשוט (`/api/usage/om-usage` / `@@om-usage`)                          | תצורת JSON (`?format=json`)                                            |
| :----------------- | :------------------------------------------------------------------------------ | :--------------------------------------------------------------------- |
| **שדה פלט**        | `NN% left` (לדוגמה, `20% left`)                                                 | `provider.quotas` / `providers[].quotas`                               |
| **מדידה**          | **הקצאה זמינה מותאמת לסף הפסקה**: הקיבולת שנותרה מעל סף ההפסקה                  | **מכסת ספק גולמית**: מדידת הספק ללא התאמות                             |
| **התאמת סף הפסקה** | מותאם באמצעות `effectiveRemainingPercent()` כך שהעתודה המוגנת מוצגת כ-`0% left` | ללא (ערכי תמונת מצב גולמיים כפי שדווחו על ידי הספק)                    |
| **נתוני סף**       | משוקללים באחוז המוצג                                                            | מאוחסנים ב-`quotaWindowThresholds` לכל חיבור (או ברירות המחדל של השרת) |
| **צרכן עיקרי**     | ממשקי CLI אינטראקטיביים, הנחיות מסוף, מפעילים אנושיים                           | אינטגרציות תכנותיות, לוחות מחוונים, ניתוח נתונים, עוקבי חיוב           |

#### נוסחת ההתאמה לסף ההפסקה

OmniRoute תומך בספי הפסקה יזומים של מכסות כדי למנוע את מיצוי משאבי הספק (המוגדרים באמצעות
`quotaWindowThresholds` של החיבור, ברירות המחדל של הספק או הגדרות חוסן גלובליות). כאשר סף הפסקה
(לדוגמה, `cutoff = 25%`) פעיל בחלון מכסה, מנגנון עיבוד הטקסט מחשב את ההקצאה שנותרה כך:

- אם `remaining <= cutoff`: מוחזר `0%`.
- אם `remaining > cutoff`: מוחזר `((remaining - cutoff) / (100 - cutoff)) * 100`.

פלט הטקסט המעוצב מעגל זאת למספר השלם הקרוב ביותר (`Math.round(...)`).

#### דוגמה להמחשה

נבחן חלון ספק עם **60% שימוש גולמי** (ולכן **40% מכסה גולמית שנותרה**) ועם סף מוגדר של
**25% הפסקה לפי מכסה שנותרה**:

| ייצוג                           | חישוב                                              |  נותרו  |              שימוש משתמע              |
| :------------------------------ | :------------------------------------------------- | :-----: | :-----------------------------------: |
| **JSON גולמי (`?format=json`)** | תמונת מצב מהספק (`quotas[window]`)                 | **40%** |                **60%**                |
| **תצורת טקסט (`NN% left`)**     | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (אם מחשבים `100 - remaining`) |

- **מדוע הטקסט מציג 20% שנותרו:** מתוך 40% המכסה הפיזית שנותרה בחשבון, 25% שמורים על ידי
  מדיניות סף ההפסקה. לקורא נותר רק מרווח שמיש של 15% מתוך 75% לפני שהנתב מפסיק
  לנתב לחיבור זה. ההתאמה מבטיחה שהחיבור מאותת על מיצוי (`0% left`) בדיוק כאשר
  הניתוב ייפסק.
- **מדוע JSON משמר ערכים גולמיים:** מטען ה-JSON מחזיר את תמונת המצב המדויקת של הספק (`UsageSnapshot`),
  כך שלכלים חיצוניים יש גישה לנתוני האמת של ניצול הספק ול-`quotaWindowThresholds`
  ברמת החיבור, ללא התאמה מאבדת מידע בצד השרת.

#### הנחיות להעברת צרכנים

אם אינטגרציה חיצונית (כגון תוסף לעורך או הרחבת סוכן) חילצה בעבר נתונים מנקודת הקצה
הטקסטואלית (`NN% left`) וחישבה את אחוז השימוש כ-`100 - NN`, מעבר ל-`?format=json` פירושו:

- קריאת ערכי JSON גולמיים תשקף את **הצריכה בפועל אצל הספק** (60% שימוש בדוגמה שלעיל).
- אם האינטגרציה מעוניינת לשמר את סמנטיקת ההקצאה הזמינה של נקודת הקצה הטקסטואלית, היא יכולה לחשב
  בצד הלקוח את נוסחת היתרה האפקטיבית באמצעות `quotaWindowThresholds` עבור דריסות ברמת החיבור.

---

## מטמון סמנטי

```bash
# קבלת נתונים סטטיסטיים של המטמון
GET /api/cache/stats

# ניקוי כל המטמונים
DELETE /api/cache/stats
```

דוגמה לתגובה:

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

### השפעה על זמן ההשהיה

פגיעה במטמון הסמנטי (HIT) מספקת את התגובה מהמטמון **ללא קריאה
לשירות במעלה הזרם**, ולכן `X-OmniRoute-Response-Latency` המדווח קרוב לאפס
(ללא תלות בזמן ההשהיה המקורי של השירות במעלה הזרם). לקוחות הרגישים לזמן השהיה
(בדיקות ביצועים, ניטור p50/p99) צריכים לבדוק את כותרת התגובה
`X-OmniRoute-Cache-Latency`:

| ערך         | משמעות                                                               |
| ----------- | -------------------------------------------------------------------- |
| `synthetic` | התגובה סופקה מהמטמון; זמן ההשהיה אינו זמן אמיתי של השירות במעלה הזרם |
| _(חסר)_     | תגובה מקריאה אמיתית לשירות במעלה הזרם                                |

### עקיפת מטמון לכל מפתח

מפתחות API יכולים לוותר על קריאות מהמטמון הסמנטי באמצעות `cacheDefaultMode`:

| ערך      | התנהגות                                                  |
| -------- | -------------------------------------------------------- |
| `legacy` | התנהגות מטמון רגילה (ברירת מחדל)                         |
| `bypass` | דילוג מלא על החיפוש במטמון; פנייה תמיד לשירות במעלה הזרם |

הגדרה בעת יצירת מפתח (`POST /api/keys`) או עדכון (`PATCH /api/keys/[id]`):

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

### עקיפה לכל בקשה

כל בקשה יכולה לעקוף את המטמון ללא תלות בהגדרות המפתח:

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

---

## לוח בקרה וניהול

נתיבי הניהול (`/api/*` למעט auth/login ציבורי) **אינם** מורשים על ידי מפתחות API רגילים של הסקה (inference). משפחות אישורים, היקפי הרשאה (scopes) ודוגמאות curl: [אימות ניהול](../guides/MANAGEMENT-AUTH.md).

### אימות

| נקודת קצה                     | מתודה    | תיאור                                                                                                                                                                                                                                                              |
| ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/auth/login`             | POST     | התחברות                                                                                                                                                                                                                                                            |
| `/api/auth/logout`            | POST     | התנתקות                                                                                                                                                                                                                                                            |
| `/api/settings/require-login` | GET/POST | סטטוס התחברות (GET, ציבורי). POST מגדיר את הסיסמה / מפעיל או מכבה את ההתחברות: למפעיל בלבד לאחר שקיימת סיסמה (סשן לוח בקרה, CLI מקומי, או התחברות מושבתת — מפתחות API וטוקנים של `oma_` מקבלים `403`); סשן לוח בקרה שולח את `currentPassword` כדי להחליף את הסיסמה |

### ניהול ספקים

| נקודת קצה                               | מתודה                     | תיאור                                                                                                                                 |
| --------------------------------------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/providers`                        | GET/POST                  | הצגת רשימה / יצירה של ספקים                                                                                                           |
| `/api/providers/[id]`                   | GET/PUT/DELETE            | ניהול ספק                                                                                                                             |
| `/api/providers/[id]/test`              | POST                      | בדיקת חיבור לספק                                                                                                                      |
| `/api/providers/[id]/models`            | GET                       | הצגת רשימת המודלים של הספק                                                                                                            |
| `/api/providers/validate`               | POST                      | אימות תצורת הספק                                                                                                                      |
| `/api/providers/bulk`                   | POST                      | הוספה מרובה של מפתחות API עבור ספק אחד בלבד                                                                                           |
| `/api/providers/import`                 | POST                      | ייבוא רשימת ספקים הטרוגנית מקובץ CSV/JSON מפוענח (#6836); תוצאות כשל חלקי ברמת השורה                                                  |
| `/api/provider-nodes*`                  | שונות                     | ניהול צמתי ספקים                                                                                                                      |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | מודלים מותאמים אישית ועקיפות ברמת המודל (הוספה, עדכון, הסתרה/הצגה, מחיקה)                                                             |
| `/api/provider-models/validate-and-add` | POST                      | אימות חיבור קפדני בהסכמה (opt-in) עם אימות ניהול, ורישום אטומי של מודל מותאם אישית; ראו [אימות מודלים](../guides/MODEL-VALIDATION.md) |

עבור מודלים שסונכרנו/יובאו, `PUT /api/provider-models` מקבל את `provider`, `modelId` ו-`maxOutputTokenOverride`: מספר שלם חיובי מגדיר את מגבלת טוקני הפלט הידנית, ו-`null` מנקה אותה כדי לשחזר את ברירת המחדל. `GET /api/provider-models?provider=<provider>` מחזיר ערכים אלה ב-`modelOutputOverrides`, כולל מודלים ללא שורת מודל מותאם אישית. העקיפה משתמשת ביכולת `max_output_tokens` של זמן הריצה ושורדת סנכרון מחדש של המודל. עמוד הספק התואם ל-OpenAI מציע את אותם פקדי עריכה/ניקוי ומסמן מודלים עם תמיכת ראייה (vision) מפורשת.

צמתי Chat Completions מותאמים אישית מתאימים ביטולי הסכמה (opt-outs) מפורשים של reasoning ל-backend של ה-upstream. בדיקת חיבור מוצלחת בוחרת באופן אוטומטי פקדי chat-template עבור כל מזהה מודל מדויק שרשומת ה-`/models` שלו מעידה על ערך `owned_by` מזוהה: `vllm`, `sglang`, או `llamacpp`. עטיפות (wrappers) שקופות התואמות ל-OpenAI עשויות לשמר את רשומת המודל המקורית בתוך אובייקט `openai` מקונן; הזיהוי עוקב אחר עד שלוש עטיפות כאלה. מודלים עם בעלות חסרה, לא מוכרת או סותרת שומרים על התנהגות OpenAI הרגילה. הזיהוי עושה שימוש חוזר בבקשת הקטלוג הקיימת, אינו מייצר טוקני completion, ומתבטל כאשר נקודת הקצה של החיבור משתנה.

כדי לנעוץ את ההתנהגות עבור backend שאינו חושף מטא-דאטה זה, השתמשו ב-API הקיים לעדכון חלקי של ספק:

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

שלחו את הגוף הזה עם `PUT /api/providers/<connection-id>`. בחיבור הזה, רמת reasoning מפורשת של `none` נשלחת כ-`chat_template_kwargs.thinking=false` וכ-`chat_template_kwargs.enable_thinking=false`. ערכי תבנית מקוריים מפורשים נשארים הסמכותיים, אלא אם כלל reasoning בצד השרת כופה רמה מסוימת. ההגדרה חלה רק כאשר חיבור מותאם אישית התואם ל-OpenAI שולח גוף Chat Completions; בקשות Responses וספקים רגילים שומרים על צורת הבקשה המקורית שלהם. הגדירו את `reasoningControl` ל-`openai` כדי לכפות העברת `reasoning_effort` רגילה של OpenAI, או השמיטו אותו/הגדירו אותו ל-`null` כדי להשתמש בזיהוי אוטומטי.

בקשות המסווג של auto-mode של Claude Code מגדירות כברירת מחדל native thinking כמושבת כאשר הן אינן מכילות בקרות reasoning מפורשות. הזיהוי משתמש בסמן המערכת של המסווג בבקשות בפורמט Claude, ולא בשמות מודלים או במגבלות השלמה. בקרות גוף מפורשות, כותרות effort/thinking נתמכות, כללי ניתוב ורמת ה-effort של המודל שנקבעה שומרים על העדיפות הקיימת שלהם. שני שלבי המסווג שומרים על הפרומפטים שלהם, מגבלות ההשלמה, רצפי העצירה ופסקי ההרשאה האמיתיים מה-upstream; השלב השני עדיין יכול להפיק את ה-reasoning הנראה המבוקש שלו כטקסט רגיל.

### זרימות OAuth

| נקודת קצה                        | מתודה   | תיאור             |
| -------------------------------- | ------- | ----------------- |
| `/api/oauth/[provider]/[action]` | Various | OAuth ספציפי לספק |

### ניתוב ותצורה

| נקודת קצה             | מתודה    | תיאור                    |
| --------------------- | -------- | ------------------------ |
| `/api/models/alias`   | GET/POST | כינויי מודלים            |
| `/api/models/catalog` | GET      | כל המודלים לפי ספק + סוג |
| `/api/combos*`        | Various  | ניהול combos             |
| `/api/keys*`          | Various  | ניהול מפתחות API         |
| `/api/pricing`        | GET      | תמחור מודלים             |

### שימוש ואנליטיקה

| נקודת קצה                        | מתודה           | תיאור                                                                                                                                                                                                                                                                                  |
| -------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | היסטוריית שימוש                                                                                                                                                                                                                                                                        |
| `/api/usage/logs`                | GET             | יומני שימוש                                                                                                                                                                                                                                                                            |
| `/api/usage/request-logs`        | GET             | יומנים ברמת הבקשה                                                                                                                                                                                                                                                                      |
| `/api/usage/[connectionId]`      | GET             | שימוש לפי חיבור                                                                                                                                                                                                                                                                        |
| `/api/usage/token-limits`        | GET/POST/DELETE | תקציבי מגבלת טוקנים לפי מפתח API                                                                                                                                                                                                                                                       |
| `/api/usage/model-latency-stats` | GET             | צבירת חביון מתגלגלת לפי ספק/מודל (avg/p50/p95/p99, שיעור הצלחה); מסננים: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                               |
| `/api/usage/cache-health`        | GET             | סיכום תקינות של מטמון פרומפטים מעל `call_logs` — יחס כתיבה/קריאה, התפלגות גודל-כתיבה p50/p90/p99, ריכוז כתיבות כבדות, חלוקה לפי מודל, ופסק דין `healthy`/`degraded`/`thrash`/`no-data`; פרמטרי שאילתה `range` (`1h`\|`24h`\|`7d`\|`30d`, ברירת מחדל `24h`) ו-`model` אופציונלי (#8827) |

### הרשאות מפתח API

`PATCH /api/keys/{id}` מעדכן את ההרשאות של מפתח קיים. כמו כל נתיב `/api/keys*`, הוא דורש הרשאת ניהול (ראו [אימות ניהול](../guides/MANAGEMENT-AUTH.md)), ולא מפתח inference. שלחו רק את השדות שברצונכם לשנות; בקשה ללא אף אחד מהם נדחית עם `No valid fields to update`. השדות המקובלים מוגדרים על ידי `updateKeyPermissionsSchema` ב-`src/shared/validation/schemas/keys.ts`.

| שדה                                         | סוג                                                                 | הערות                                                                                                                 |
| ------------------------------------------- | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | string, ‏1-200 תווים                                                |                                                                                                                       |
| `isActive`                                  | boolean                                                             |                                                                                                                       |
| `isBanned`                                  | boolean                                                             |                                                                                                                       |
| `expiresAt`                                 | תאריך-שעה בפורמט ISO 8601 או `null`                                 | `null` מנקה את תאריך התפוגה                                                                                           |
| `modelAccessMode`                           | `all` \| `restricted`                                               | `allowedModels` חייב להיות ריק כאשר המצב הוא `all`                                                                    |
| `allowedModels`, `blockedModels`            | מערך של מחרוזות, עד 1000                                            |                                                                                                                       |
| `allowedCombos`                             | מערך של מחרוזות, עד 500                                             | שולט לאילו קומבו המפתח רשאי לקרוא; מודלים ישירים נשלטים על ידי `modelAccessMode` / `allowedModels`                    |
| `connectionAccessMode`                      | `all` \| `restricted`                                               | `allowedConnections` חייב להיות לא-ריק כאשר `restricted` וריק כאשר `all`                                              |
| `allowedConnections`                        | מערך של UUIDs, עד 100                                               |                                                                                                                       |
| `allowAutoCombos`                           | boolean                                                             | `false` דוחה בקשות למודלים `auto/*` עם מפתח זה; מפתחות שמעולם לא הגדירו אותו מורשים                                   |
| `catalogScope`                              | `all` \| `combos` \| `models`                                       | מה ש-`GET /v1/models` מציג עבור מפתח זה (קומבו בלבד, מודלים בלבד, או שניהם); זה לא משנה לאילו מודלים המפתח רשאי לקרוא |
| `forcedModel`                               | מחרוזת עד 300 תווים, או `null`                                      | מנתב בקשות צ'אט למודל/קומבו זה, בעדיפות על פני `X-Route-Model` ו-`body.model`; המגבלות של המפתח עדיין חלות            |
| `noLog`, `autoResolve`                      | boolean                                                             |                                                                                                                       |
| `throttleDelayMs`                           | מספר שלם, ‏0-300000                                                 |                                                                                                                       |
| `maxSessions`                               | מספר שלם, ‏0-10000                                                  |                                                                                                                       |
| `rateLimits`                                | מערך של `{ limit, window }` (מספרים שלמים חיוביים, עד 50) או `null` | `null` מנקה את המגבלות                                                                                                |
| `accessSchedule`                            | אובייקט לוח זמנים או `null`                                         | `null` מנקה את לוח הזמנים                                                                                             |
| `scopes`                                    | מערך של מחרוזות, עד 32                                              |                                                                                                                       |
| `allowedEndpoints`                          | מערך של מחרוזות, עד 20                                              |                                                                                                                       |
| `streamDefaultMode`                         | `legacy` \| `json`                                                  |                                                                                                                       |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                                | ראה [עקיפת מטמון לפי מפתח](#per-key-cache-bypass)                                                                     |
| `compressionEnabled`                        | boolean                                                             |                                                                                                                       |
| `codexServiceMode`                          | אחד ממצבי השירות של Codex                                           |                                                                                                                       |
| `disableNonPublicModels`                    | boolean                                                             |                                                                                                                       |
| `allowUsageCommand`                         | boolean                                                             |                                                                                                                       |
| `usageLimitEnabled`                         | boolean                                                             |                                                                                                                       |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | number >= 0 or `null`                                               |                                                                                                                       |
| `chaosModeEnabled`                          | boolean                                                             |                                                                                                                       |

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

### הגדרות

| נקודת קצה                             | מתודה         | תיאור                                                                                                                                                                                                                                                  |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/settings`                       | GET/PUT/PATCH | הגדרות כלליות. מפתחות מדיניות-אבטחה (`requireLogin`, `newPassword`, `oidc*`, `corsOrigins`, `bruteForceProtection`) דורשים `currentPassword` ואישור מפעיל — מפתחות API וטוקני `oma_` מקבלים `403`; כל שינוי (mutation) דורש את היקף טוקן הגישה `admin` |
| `/api/settings/proxy`                 | GET/PUT       | הגדרות פרוקסי רשת                                                                                                                                                                                                                                      |
| `/api/settings/proxy/test`            | POST          | בדיקת חיבור פרוקסי                                                                                                                                                                                                                                     |
| `/api/settings/ip-filter`             | GET/PUT       | רשימת היתר/חסימה של IP                                                                                                                                                                                                                                 |
| `/api/settings/thinking-budget`       | GET/PUT       | מצב שכתוב **בקשות** thinking/reasoning ‏(passthrough / auto-strip / custom / adaptive). בלתי תלוי בדחיסה. ראו [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md).                                                                                      |
| `/api/settings/system-prompt`         | GET/PUT       | פרומפט מערכת גלובלי                                                                                                                                                                                                                                    |
| `/api/settings/compression`           | GET/PUT       | הגדרות דחיסה גלובליות                                                                                                                                                                                                                                  |
| `/api/settings/purge-request-history` | POST          | מחיקת שורות יומן הבקשות וארטיפקטים מקומיים של יומן קריאות                                                                                                                                                                                              |

### הקשר ודחיסה

| נקודת קצה                              | שיטה           | תיאור                                                                |
| -------------------------------------- | -------------- | -------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | תצוגה מקדימה של דחיסה off/lite/standard/aggressive/ultra/RTK/stacked |
| `/api/compression/language-packs`      | GET            | רשימת חבילות השפה הזמינות של Caveman                                 |
| `/api/compression/rules`               | GET            | רשימת מטא-דאטה של כללי Caveman                                       |
| `/api/context/caveman/config`          | GET/PUT        | כינוי להגדרות ספציפיות ל-Caveman                                     |
| `/api/context/rtk/config`              | GET/PUT        | הגדרות ספציפיות ל-RTK, כולל מסננים מותאמים אישית ושמירת פלט גולמי    |
| `/api/context/rtk/filters`             | GET            | קטלוג מסנני RTK ואבחון מסננים מותאמים אישית                          |
| `/api/context/rtk/test`                | POST           | הרצת תצוגה מקדימה/בדיקת RTK על מטען טקסט                             |
| `/api/context/rtk/raw-output/[id]`     | GET            | קריאת פלט גולמי מצונזר שנשמר לפי מזהה מצביע                          |
| `/api/context/combos`                  | GET/POST       | רשימה/יצירה של שילובי דחיסה                                          |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | פרטים/עדכון/מחיקה של שילוב דחיסה                                     |
| `/api/context/combos/[id]/assignments` | GET/PUT        | שיוך שילובי דחיסה לשילובי ניתוב                                      |
| `/api/context/analytics`               | GET            | כינוי לאנליטיקת דחיסה                                                |

### ניטור

| נקודת קצה                            | שיטה       | תיאור                                                                                                                                                                                                                                                                                                                                                                           |
| ------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | מעקב אחר סשנים פעילים                                                                                                                                                                                                                                                                                                                                                           |
| `/api/rate-limits`                   | GET        | מגבלות קצב לפי חשבון                                                                                                                                                                                                                                                                                                                                                            |
| `/api/monitoring/health`             | GET        | בדיקת תקינות + סיכום ספקים (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). תצוגת הניהול כוללת `credentialHealth`: סקלרים של מטמון הבדיקות, `failedConnections` כאשר `failed>0`, ו-`staleDbNonOkCount` (`test_status` דביק של SQLite, לא המדיד). ראו [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status). |
| `/api/cache/stats`                   | GET/DELETE | סטטיסטיקות מטמון / ניקוי                                                                                                                                                                                                                                                                                                                                                        |
| `/api/modality-bridge/stats`         | GET        | `attempts` בזיכרון, הצלחות/`bridged`, כישלונות, פגיעות מטמון, `totalLatencyMs`, `latencySamples`, `averageLatencyMs` המחושב לפי מספר הדגימות, וזמן שימוש אחרון (מתאפס בהפעלה מחדש; אימות ניהול)                                                                                                                                                                                 |
| `/api/modality-bridge/video/runtime` | GET        | בדיקת trusted-loopback מחמירה לפני אימות/בדיקת ניהול; זמינות וגרסאות מסוננות של FFmpeg/ffprobe (no-store)                                                                                                                                                                                                                                                                       |
| `/api/modality-bridge/video/extract` | POST       | מתווך בתים פנימי מאומת מסוג trusted-loopback; קלט 50 MiB, תור חסום/פלט 32 MiB, `503` לקיבולת, `499` לניתוק, `504` לדדליין; לא API ציבורי להעלאה                                                                                                                                                                                                                                 |

### גיבוי וייצוא/ייבוא

| נקודת קצה                   | שיטה   | תיאור                                                            |
| --------------------------- | ------ | ---------------------------------------------------------------- |
| `/api/db-backups`           | GET    | הצגת רשימת גיבויים זמינים                                        |
| `/api/db-backups`           | PUT    | יצירת גיבוי ידני                                                 |
| `/api/db-backups`           | POST   | שחזור מגיבוי ספציפי                                              |
| `/api/db-backups`           | PATCH  | שמירת הגדרות שמירת גיבויים (למפעילים בלבד)                       |
| `/api/db-backups`           | DELETE | קיצוץ גיבויים מאוחסנים בהתאם להגדרות השמירה (למפעילים בלבד)      |
| `/api/db-backups/export`    | GET    | הורדת מסד הנתונים כקובץ .sqlite                                  |
| `/api/db-backups/import`    | POST   | העלאת קובץ .sqlite להחלפת מסד הנתונים (`?dryRun=true` מאמת בלבד) |
| `/api/db-backups/exportAll` | GET    | הורדת גיבוי מלא כארכיון .tar.gz                                  |

`/api/db-backups/export`, `/api/db-backups/exportAll` ו-`/api/settings/export-json` מוסרים
את כל אישור (credential) מאוחסן, ולכן הם דורשים את סשן לוח הבקרה או את ה-CLI המקומי (או
התחברות מושבתת). מפתחות API מכל היקף ואסימוני גישה מסוג `oma_` מקבלים `403`. פעולות השחזור
שומרות על אותו גבול: `POST /api/db-backups/import` (כולל `dryRun=true`), `POST /api/db-backups`
(שחזור לפי id) ו-`POST /api/settings/import-json` מחליפים את מסד הנתונים או את ההגדרות הפעילים,
ולכן אישור מכונה מקבל `403` גם שם; `omniroute sync import` שולח את אישור ה-CLI המקומי. כך גם
`DELETE /api/db-backups` (קיצוץ גיבויים מאוחסנים) ו-`PATCH /api/db-backups` (הגדרות שמירה:
הערכים הנשמרים מניעים את הקיצוץ האוטומטי לאחר כל גיבוי). שליפת רשימה (`GET`) ויצירת
גיבוי ידני (`PUT`) נשארות עם אימות ניהול רגיל.

### סנכרון ענן

| נקודת קצה              | שיטה  | תיאור             |
| ---------------------- | ----- | ----------------- |
| `/api/sync/cloud`      | שונות | פעולות סנכרון ענן |
| `/api/sync/initialize` | POST  | אתחול סנכרון      |
| `/api/cloud/*`         | שונות | ניהול ענן         |

### מנהרות (Tunnels)

| נקודת קצה                  | שיטה | תיאור                                                               |
| -------------------------- | ---- | ------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET  | קריאת סטטוס התקנה/ריצה של Cloudflare Quick Tunnel עבור לוח הבקרה    |
| `/api/tunnels/cloudflared` | POST | הפעלה או השבתה של Cloudflare Quick Tunnel (`action=enable/disable`) |
| `/api/tunnels/ngrok`       | GET  | קריאת סטטוס ריצה של ngrok Tunnel עבור לוח הבקרה                     |
| `/api/tunnels/ngrok`       | POST | הפעלה או השבתה של ngrok Tunnel (`action=enable/disable`)            |

### כלי CLI

| נקודת קצה                          | שיטה | תיאור                   |
| ---------------------------------- | ---- | ----------------------- |
| `/api/cli-tools/claude-settings`   | GET  | סטטוס Claude CLI        |
| `/api/cli-tools/codex-settings`    | GET  | סטטוס Codex CLI         |
| `/api/cli-tools/droid-settings`    | GET  | סטטוס Droid CLI         |
| `/api/cli-tools/openclaw-settings` | GET  | סטטוס OpenClaw CLI      |
| `/api/cli-tools/runtime/[toolId]`  | GET  | סביבת ריצה גנרית של CLI |

תגובות CLI כוללות: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### סוכני ACP

| נקודת קצה         | שיטה   | תיאור                                                    |
| ----------------- | ------ | -------------------------------------------------------- |
| `/api/acp/agents` | GET    | רשימת כל הסוכנים שזוהו (מובנים + מותאמים אישית) עם סטטוס |
| `/api/acp/agents` | POST   | הוספת סוכן מותאם אישית או רענון מטמון הזיהוי             |
| `/api/acp/agents` | DELETE | הסרת סוכן מותאם אישית לפי פרמטר שאילתה `id`              |

תגובת GET כוללת `agents[]` (id, name, binary, version, installed, protocol, isCustom) ו-`summary` (total, installed, notFound, builtIn, custom).

### שרידות ומגבלות קצב

| נקודת קצה                         | שיטה      | תיאור                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | קבלה/עדכון של תור בקשות, צינון חיבור, מפסק ספק והגדרות המתנה                                                                                                                                                                                                                                                                                                   |
| `/api/resilience/reset`           | POST      | איפוס מפסקי המעגל של הספקים                                                                                                                                                                                                                                                                                                                                    |
| `/api/resilience/model-cooldowns` | GET       | רשימת נעילות פעילות לפי (ספק, חיבור, מודל), ממוינות לפי זמן נותר                                                                                                                                                                                                                                                                                               |
| `/api/resilience/model-cooldowns` | DELETE    | ניקוי נעילת מודל — גוף `{provider, model}` או `{all: true}` למחיקת הכל                                                                                                                                                                                                                                                                                         |
| `/api/rate-limits`                | GET/POST  | סטטוס מגבלת קצב לפי חשבון (GET) או הפעלה/כיבוי של הגנת מגבלת קצב עבור חיבור (POST `{connectionId, enabled}`). נתיב הכתיבה הנתמך עבור `rateLimitProtection` (לעולם לא משתנה דרך `PUT /api/providers/[id]`). הערה: `enabled: false` משבית הגנה מפורשת אך אינו מוציא חיבור מפתח API פעיל מרשת הביטחון של ההפעלה האוטומטית הגלובלית (`autoEnableApiKeyProviders`). |
| `/api/rate-limit`                 | GET       | תצורת מגבלת קצב גלובלית (מיושן; כינוי ל-`/api/rate-limits`)                                                                                                                                                                                                                                                                                                    |

> כל ארבעת נתיבי `/api/resilience/*` דורשים **אימות ניהול** (`requireManagementAuth`). ראו [חוסן (מורחב)](#resilience-extended) לפירוט מלא של מפסק ספק מול צינון חיבור מול נעילת מודל.

### הערכות (Evals)

| נקודת קצה    | שיטה     | תיאור                           |
| ------------ | -------- | ------------------------------- |
| `/api/evals` | GET/POST | רשימת חבילות הערכה / הרצת הערכה |

### מדיניות

| נקודת קצה       | שיטה            | תיאור               |
| --------------- | --------------- | ------------------- |
| `/api/policies` | GET/POST/DELETE | ניהול מדיניות ניתוב |

### תאימות

| נקודת קצה                   | שיטה | תיאור                          |
| --------------------------- | ---- | ------------------------------ |
| `/api/compliance/audit-log` | GET  | יומן ביקורת תאימות (N אחרונים) |

### v1beta (תואם Gemini)

| נקודת קצה                  | שיטה | תיאור                                 |
| -------------------------- | ---- | ------------------------------------- |
| `/v1beta/models`           | GET  | רשימת מודלים בפורמט Gemini            |
| `/v1beta/models/{...path}` | POST | נקודת קצה `generateContent` של Gemini |

נקודות קצה אלה משקפות את פורמט ה-API של Gemini עבור לקוחות המצפים לתאימות מקורית ל-SDK של Gemini.

### ממשקי API פנימיים / מערכת

| נקודת קצה                | שיטה | תיאור                                      |
| ------------------------ | ---- | ------------------------------------------ |
| `/api/init`              | GET  | בדיקת אתחול אפליקציה (בשימוש בהרצה ראשונה) |
| `/api/tags`              | GET  | תגי מודל תואמי Ollama (עבור לקוחות Ollama) |
| `/api/restart`           | POST | הפעלת אתחול חינני של השרת                  |
| `/api/shutdown`          | POST | הפעלת כיבוי חינני של השרת                  |
| `/api/system/env/repair` | POST | תיקון משתני סביבה של ספק OAuth             |
| `/api/system/version`    | GET  | גרסה נוכחית/אחרונה, סטטוס עדכון, ערוץ הפצה |
| `/api/system/version`    | POST | התחלת עדכון מודע-פריסה לגרסה האחרונה       |

> **הערה:** נקודות קצה אלה משמשות באופן פנימי על ידי המערכת או לתאימות לקוח Ollama. בדרך כלל משתמשי קצה אינם קוראים להן.

### תיקון סביבת OAuth _(v3.6.1+)_

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

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

מתקן משתני סביבה חסרים או פגומים של OAuth עבור ספק מסוים. מחזיר:

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

### גרסה וערוץ הפצה

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

נתיב ניהול ל-loopback בלבד (אימות admin). מחזיר את הגרסה הרצה, את הגרסה העדכנית ביותר שפורסמה ואת סטטוס העדכון האוטומטי. `releaseChannel` ו-`channels` הם שדות מתווספים (rail 3.8.54); `channel` שומר על משמעותו — מצב הפריסה שבו משתמש מנגנון העדכון של לוח הבקרה (`npm`, `source` או `docker-compose`).

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

- `releaseChannel` — ערוץ ה-npm של הבנייה הרצה: `nightly` עבור גרסאות `-nightly.*`, `next` עבור שאר גרסאות הטרום-השקה (`-rc.*`, `-beta.*`, `-alpha.*`), `lts` עבור גרסה יציבה של major ישן יותר מ-`channels.latest`, אחרת `latest`. אותם כללים כמו ב-`scripts/release/dist-tag.mjs`, שבוחר את ה-dist-tag של npm בזמן הפרסום.
- `channels` — ה-head הפרסום של כל dist-tag, מ-`npm view omniroute dist-tags` (גיבוי HTTP מול ה-registry), נשמר במטמון עם אותו TTL של 10 דקות כמו `latest`. `latest` קיים תמיד (עם נפילה חזרה לשדה `latest`, ואז ל-`"unavailable"`); `next`, `nightly` ו-`lts` מופיעים רק כאשר ה-dist-tag ההוא קיים. בקשת `Cache-Control: no-cache` מרעננת את שתי הבדיקות.

מודל הערוצים (`latest` = v3 עד ה-GA של 4.0, `next` = rc, `nightly` = בנייות `develop`, `lts` = תיקוני v3 אחרי ה-GA של 4.0) מתואר ב-`docs/ops/RELEASE_STRATEGY.md`.

---

## תמלול אודיו

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

תמללו קובצי אודיו באמצעות כל ספק STT שהוגדר. מקטע הנתיב הראשון
בוחר את הספק המקורי (`openai/…`, `deepgram/…`). שערים שמייצאים מחדש מודל של ספק אחר משתמשים במזהה מלא
(`openrouter/deepgram/nova-3`).

**בקשה:**

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

**תגובה:**

```json
{
  "text": "שלום, זהו תוכן האודיו שתומלל.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}
```

**דוגמאות למזהי מודלים:** `openai/whisper-1` (דורש מפתח OpenAI),
`openrouter/deepgram/nova-3` (דורש מפתח OpenRouter),
`deepgram/nova-3` (דורש מפתח מקורי של Deepgram). בקשה ישירה מסוג
`deepgram/nova-3` **אינה** משתמשת ב-OpenRouter.

**פורמטים נתמכים:** `mp3`, `wav`, `m4a`, `flac`, `ogg`, `webm`.

---

## תאימות ל-Ollama

עבור לקוחות המשתמשים בפורמט ה-API של Ollama:

```bash
# נקודת קצה לצ'אט (פורמט Ollama)
POST /v1/api/chat

# הצגת רשימת מודלים (פורמט Ollama)
GET /api/tags
```

הבקשות מתורגמות אוטומטית בין הפורמטים של Ollama והפורמטים הפנימיים.

## כינויים מתומחררים עבור VS Code / ללא כותרת

השתמשו בכינויים אלה כאשר שילוב אינו יכול להזריק כותרת `Authorization` ודורש שמפתח ה-API יוטמע בכתובת ה-URL הבסיסית.

```bash
# כינוי לקטלוג בסגנון OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# כינויים לצ'אט בסגנון OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# כינויים בסגנון Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

דוגמה:

```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":"שלום"}]}'
```

הערות:

- הכינויים המתומחררים משתמשים מחדש באותם מטפלים כמו `/v1/*` ו-`/api/tags`; מבני התגובות נשארים זהים.
- העדיפו את `Authorization: Bearer ...` בכל פעם שהלקוח תומך בכותרות מותאמות אישית.
- אסימונים המבוססים על כתובות URL עשויים להופיע ביומני רישום של שרתי proxy הפוכים, בהיסטוריית הדפדפן ובטלמטריה מחוץ ל-OmniRoute. התייחסו אליהם כאפשרות תאימות, ולא כמצב האימות המוגדר כברירת מחדל.

---

## טלמטריה

```bash
# קבלת סיכום טלמטריית השהיה (p50/p95/p99 לכל ספק)
GET /api/telemetry/summary
```

**תגובה:**

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

---

## תקציב

```bash
# קבלת מצב התקציב עבור כל מפתחות ה-API
GET /api/usage/budget

# הגדרה או עדכון של תקציב
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"
}
```

> **הערות לגבי הסכימה** (`setBudgetSchema`): השדה `apiKeyId` הוא שדה חובה; לפחות אחד מבין `dailyLimitUsd`, `weeklyLimitUsd` או `monthlyLimitUsd` חייב להיות גדול מאפס. שדות אופציונליים: `warningThreshold` ‏(0–1), `resetInterval` ‏(`daily` | `weekly` | `monthly`), `resetTime` ‏(`HH:MM`). המבנה הקודם `{keyId, limit, period}` מחזיר `400 Bad Request`.

## מגבלות טוקנים

תקציבי **טוקנים** לכל מפתח API (בנפרד מהתקציב מבוסס ה-USD שלעיל). הם נאכפים ישירות בנתיב הבקשה: כאשר השימוש בחלון הנוכחי של מפתח מגיע למגבלה שלו, בקשות נדחות עם `429 Too Many Requests`. ניתן להחיל מגבלות על `model` מסוים, על `provider`, או באופן `global` על פני המפתח כולו; כאשר מספר מגבלות תואמות לבקשה, המגבלה המחמירה ביותר גוברת.

```bash
# הצגת מגבלות הטוקנים של מפתח (כולל השימוש הנוכחי בחלון)
GET /api/usage/token-limits?apiKeyId=key-123

# יצירה או עדכון של מגבלת טוקנים
POST /api/usage/token-limits
Content-Type: application/json

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

# מחיקת מגבלת טוקנים לפי מזהה
DELETE /api/usage/token-limits?id=tl-abc
```

> **הערות סכימה** (`setTokenLimitSchema`): השדות `apiKeyId` ו-`scopeType` (`model` | `provider` | `global`) הם שדות חובה. השדה `scopeValue` נדרש אלא אם `scopeType` הוא `global` (למשל, מזהה מודל עבור תחום `model`, או מזהה ספק עבור תחום `provider`). הערך `tokenLimit` חייב להיות מספר שלם חיובי (מומר ממחרוזת). אופציונלי: `id` (יש להשמיט כדי ליצור, ולספק כדי לעדכן), `resetInterval` (`daily` | `weekly` | `monthly`, ברירת המחדל היא `monthly`), `resetTime` (`HH:MM`), `enabled` (ברירת המחדל היא `true`). תגובות `GET` מעשירות כל מגבלה בשדות `tokensUsed`, `remaining`, `windowStart`, `periodStartAt` ו-`nextResetAt`. זוהי נקודת קצה מסוג ניהול (האימות נאכף באופן מרכזי על ידי צינור ההרשאות).

## עיבוד בקשות

1. הלקוח שולח בקשה אל `/v1/*`
2. מטפל הנתיב קורא ל-`handleChat`, ל-`handleEmbedding`, ל-`handleAudioTranscription` או ל-`handleImageGeneration`
3. המודל מזוהה (ספק/מודל ישיר או כינוי/שילוב)
4. פרטי גישה נבחרים ממסד הנתונים המקומי, עם סינון לפי זמינות החשבון
5. עבור צ'אט: `handleChatCore` בודק את מטמון הסמנטיקה/החתימות ומזהה את הגדרות הדחיסה של השילוב
6. דחיסה יזומה מופעלת לפני התרגום לספק כאשר היא מופעלת (`lite`,‏ Caveman,‏ RTK או שילוב שכבות)
7. מנגנון הביצוע של הספק שולח את הבקשה לשירות המקור
8. התגובה מתורגמת בחזרה לפורמט הלקוח (צ'אט) או מוחזרת כפי שהיא (הטמעות/תמונות/שמע)
9. נתוני שימוש, ניתוחי דחיסה ויומני בקשות נרשמים
10. במקרה של שגיאות, מופעל מנגנון גיבוי בהתאם לכללי השילוב

הפניה לארכיטקטורה המלאה: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## ניהול שילובים

ניתן גם למפות שילובי ניתוב ברמה גבוהה יותר (שכבר סוכמו תחת `/api/combos*`) ביחס של 1:1 מתבנית מזהה מודל, וכך לאפשר הפניה שקופה של מזהה מודל בסגנון OpenAI לשילוב.

| שיטה   | נתיב                             | תיאור                                                                            |
| ------ | -------------------------------- | -------------------------------------------------------------------------------- |
| GET    | `/api/model-combo-mappings`      | הצגת כל מיפויי מודל→שילוב                                                        |
| POST   | `/api/model-combo-mappings`      | יצירת מיפוי — גוף הבקשה: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | אחזור מיפוי יחיד                                                                 |
| PUT    | `/api/model-combo-mappings/[id]` | עדכון שדות של מיפוי קיים                                                         |
| DELETE | `/api/model-combo-mappings/[id]` | הסרת מיפוי                                                                       |

**אימות:** הפעלת ניהול/מפתח API (`requireManagementAuth`).

---

## Webhooks

מינויים ל-webhook יוצא עבור אירועי OmniRoute (השלמת בקשה, מיצוי מכסה, רוטציית מפתח וכו').

| שיטה   | נתיב                      | תיאור                                                                     |
| ------ | ------------------------- | ------------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | הצגת רשימת webhooks (הסודות ממוסכים כ-`<prefix>...`)                      |
| POST   | `/api/webhooks`           | יצירת webhook — גוף הבקשה: `{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | אחזור webhook                                                             |
| PUT    | `/api/webhooks/[id]`      | עדכון url/events/secret/description                                       |
| DELETE | `/api/webhooks/[id]`      | הסרת webhook                                                              |
| POST   | `/api/webhooks/[id]/test` | שליחת מטען בדיקה לכתובת ה-URL של ה-webhook והחזרת סטטוס המסירה            |

**אימות:** הפעלת ניהול/מפתח API (`requireManagementAuth`).

---

## מפתחות רשומים (ניהול אוטומטי)

משמש את תת-המערכת לניהול אוטומטי של מפתחות לצורך הנפקה ותחלופה של מפתחות API מול ספק/חשבון מגבה, עם מכסות יומיות/שעתיות.

| שיטה   | נתיב                                  | תיאור                                                                                                                                                                                               |
| ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | הצגת המפתחות הרשומים (קידומת מוסווית בלבד)                                                                                                                                                          |
| POST   | `/api/v1/registered-keys`             | הנפקת מפתח רשום חדש — גוף הבקשה: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. מחזיר את המפתח הגולמי **פעם אחת**. מחזיר `429` במקרה של דחייה עקב מכסה. |
| GET    | `/api/v1/registered-keys/[id]`        | אחזור המטא-נתונים של מפתח רשום (ללא חומר המפתח הגולמי)                                                                                                                                              |
| DELETE | `/api/v1/registered-keys/[id]`        | ביטול מפתח רשום                                                                                                                                                                                     |
| POST   | `/api/v1/registered-keys/[id]/revoke` | נקודת קצה מפורשת לביטול (אותה השפעה כמו DELETE)                                                                                                                                                     |

**אימות:** הפעלת ניהול/מפתח API (`requireManagementAuth`) — אותו מנגנון הגנה כמו ב-`/api/keys`: הפעלת לוח מחוונים, אסימון CLI מקומי, או מפתח API עם היקף `manage`/`admin`; מפתחות API להסקה בלבד מקבלים `403`. ראו גם `/v1/quotas/check` ו-`/v1/issues/report`.

---

## פרוטוקול סוכנים

משימות של סוכני ענן (Claude Code, Codex Cloud, OpenHands וכו׳) המבוצעות מרחוק בשם משתמשי OmniRoute.

| שיטה   | נתיב                          | תיאור                                                                                                                                          |
| ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | הצגת רשימת משימות — פרמטרים אופציונליים: `?provider=`, `?status=`, `?limit=` (1–500, ברירת מחדל 50)                                            |
| POST   | `/api/v1/agents/tasks`        | יצירת משימה — גוף הבקשה מאומת באמצעות `CreateCloudAgentTaskSchema` (`providerId`, `prompt`, `source`, `options?`). מחזיר `201` עם מעטפת המשימה |
| DELETE | `/api/v1/agents/tasks?id=...` | מחיקת משימה                                                                                                                                    |
| GET    | `/api/v1/agents/tasks/[id]`   | קריאת משימה — מרענן באופן סינכרוני את הסטטוס מסוכן הענן החיצוני כאשר מוגדר `external_id`                                                       |
| POST   | `/api/v1/agents/tasks/[id]`   | פעולה מובחנת: `{action: "approve"}`, `{action: "message", message}`, או `{action: "cancel"}`                                                   |
| DELETE | `/api/v1/agents/tasks/[id]`   | מחיקת משימה מסוימת לפי מזהה                                                                                                                    |

> **אימות:** נדרש אימות ניהול בכל מתודה (`requireCloudAgentManagementAuth`). לפני v3.8.0 נקודות קצה אלה לא דרשו אימות — ראו את הקומיט `588a0333` לגבי השינוי שאינו תואם לאחור.

```bash
# יצירת משימת ענן של Claude Code
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":"..."}}'
```

---

## שרתי Proxy לניהול

שרתי Proxy יוצאים מסוג HTTP(S)/SOCKS שניתן להקצות לספקים, לחשבונות או באופן גלובלי.

| שיטה   | נתיב                                         | תיאור                                                                                                                                              |
| ------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | הצגת רשימת שרתי Proxy (עם `?id=` מוחזר שרת אחד; עם `?id=&where_used=1` מוחזר גרף ההקצאות)                                                          |
| POST   | `/api/v1/management/proxies`                 | יצירת שרת Proxy — גוף הבקשה מאומת באמצעות `createProxyRegistrySchema`                                                                              |
| PATCH  | `/api/v1/management/proxies`                 | עדכון שרת Proxy — גוף הבקשה מאומת באמצעות `updateProxyRegistrySchema` (נדרש `id`)                                                                  |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | מחיקת שרת Proxy (השתמשו ב־`force=1` כדי לנתק הקצאות)                                                                                               |
| GET    | `/api/v1/management/proxies/assignments`     | הצגת רשימת הקצאות — ניתן לסנן לפי `proxy_id`,‏ `scope`,‏ `scope_id`; העבירו `resolve_connection_id=<id>` כדי לזהות את שרת ה־Proxy הפעיל עבור חיבור |
| PUT    | `/api/v1/management/proxies/assignments`     | הקצאה — גוף הבקשה מאומת באמצעות `proxyAssignmentSchema` (`{scope, scopeId?, proxyId?}`). מנקה את מטמון המנתב                                       |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | הקצאה מרוכזת — גוף הבקשה מאומת באמצעות `bulkProxyAssignmentSchema` (`{scope, scopeIds[], proxyId?}`)                                               |
| GET    | `/api/v1/management/proxies/health?hours=24` | נתוני תקינות מצטברים של שרתי Proxy (מספר הצלחות/כישלונות, זמן השהיה) לאורך חלון זמן                                                                |

**אימות:** נדרשים סשן ניהול/מפתח API בכל נתיב (`requireManagementAuth`).

> הנתיבים `POST /api/v1/management/proxies/[id]/assignments` ו־`POST /api/v1/management/proxies/[id]/health` שבתיאור המשימה מטופלים באמצעות הנתיבים השטוחים `/assignments` ו־`/health` המוצגים לעיל — אין בבסיס הקוד נתיבי משנה נפרדים לכל מזהה.

---

## שרידות (מורחב)

OmniRoute חושף שלושה מנגנוני כשל זמני עצמאיים; נקודות הקצה לניהול שלהלן מאפשרות למפעילים לקרוא ולעקוף אותם:

| היקף            | אחסון מצב                           | קריאה                                     | איפוס / ניקוי                               |
| --------------- | ----------------------------------- | ----------------------------------------- | ------------------------------------------- |
| מפסק זרם של ספק | `domain_circuit_breakers` + בזיכרון | `/api/monitoring/health`                  | `POST /api/resilience/reset`                |
| צינון חיבור     | `rateLimitedUntil` על חיבורי ספקים  | `/api/rate-limits`, `/api/providers/[id]` | (מופעל מחדש בעצלתיים; מנוקה דרך PUT של ספק) |
| נעילת מודל      | רישום זמינות-מודלים בזיכרון         | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`    |

`PATCH /api/resilience` מקבל עקיפות של מפסק זרם של ספק תחת `providerBreaker.oauth` ו-`providerBreaker.apikey`. כל פרופיל תומך ב-`degradationThreshold`, `failureThreshold` ו-`resetTimeoutMs`; אותם שדות חשופים בלוח מחוונים → הגדרות → שרידות.

```bash
# ניקוי נעילת מודל בודדת
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"}'

# מחיקת כל הנעילות
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'
```

הפניה רעיונית מלאה וברירות מחדל של מפסק זרם: ראו [`CLAUDE.md`](../../CLAUDE.md) ← "Resilience Runtime State" ו-[`docs/architecture/RESILIENCE_GUIDE.md`](../architecture/RESILIENCE_GUIDE.md).

### תור הגבלת קצב ורשת ביטחון להפעלה אוטומטית

- **נתיב כתיבה נתמך**: `POST /api/rate-limits` עם גוף `{"connectionId": "<id>", "enabled": true|false}` הוא נקודת הקצה הנתמכת לניהול להחלפת מצב הגנת הגבלת קצב עבור חיבור. `PUT /api/providers/[id]` במכוון אינו משנה או מחליף את `rateLimitProtection` (#11278).
- **סמנטיקה של `enabled: false`**: הגדרת `enabled: false` מסירה הגנה מפורשת עבור החיבור, אך **אינה** מוציאה חיבור פעיל עם מפתח API מרשת הביטחון הגלובלית להפעלה אוטומטית (`autoEnableApiKeyProviders = true`). ב-`reconcileEnabledConnections` (`open-sse/services/rateLimitManager.ts`), `false` ו-`undefined` שקולים; חיבורי מפתח API פעילים ללא הגנה מפורשת נשארים מוגנים תחת רשת הביטחון להפעלה אוטומטית.
- **השבתה גלובלית**: כדי להריץ חיבורי מפתח API ללא תורי הגבלת קצב, השביתו את רשת הביטחון באופן גלובלי דרך `RATE_LIMIT_AUTO_ENABLE=false` (משתנה סביבה) או `resilienceSettings.requestQueue.autoEnableApiKeyProviders = false` (הגדרות → שרידות / `PATCH /api/resilience`).

---

## מיומנויות

מסגרת מיומנויות להרחבת OmniRoute באמצעות מטפלים מותאמים אישית הניתנים להפעלה, לצד שילובים עם זירות מסחר.

| שיטה   | נתיב                              | תיאור                                                                                                                   |
| ------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`                     | הצגת המיומנויות המותקנות — ניתן לסינון לפי `?q=`, `?mode=on\|off\|auto`, `?source=skillsmp\|skillssh\|local`, עם עימוד  |
| GET    | `/api/skills/[id]`                | אחזור מיומנות אחת                                                                                                       |
| PUT    | `/api/skills/[id]`                | עדכון מיומנות (שם, תיאור, מצב, סכימה, מטפל, תגיות)                                                                      |
| DELETE | `/api/skills/[id]`                | הסרת התקנה של מיומנות                                                                                                   |
| POST   | `/api/skills/install`             | התקנת מיומנות ממניפסט גולמי — גוף הבקשה: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}` |
| GET    | `/api/skills/executions`          | הצגת הפעלות מיומנות אחרונות (יומן ביקורת הכולל קלטים/פלטים/משך זמן)                                                     |
| GET    | `/api/skills/marketplace?q=...`   | חיפוש/רשימת פריטים פופולריים מזירת המסחר SkillsMP (מחייב את ההגדרה `skillsmpApiKey`)                                    |
| POST   | `/api/skills/marketplace/install` | התקנת מיומנות לפי מזהה מ-SkillsMP                                                                                       |
| GET    | `/api/skills/skillssh?q=&limit=`  | חיפוש במרשם skills.sh                                                                                                   |
| POST   | `/api/skills/skillssh/install`    | התקנת מיומנות לפי מזהה מ-skills.sh                                                                                      |

**אימות:** הפעלת ניהול/מפתח API. נתיבי החיפוש בזירת המסחר מקבלים אימות ניהול או מפתח API מסוג Bearer (`isAuthenticated`).

---

## זיכרון

מאגר זיכרון מתמשך לשיחות ולעובדות, המוגדר בהיקף של מפתח API / הפעלה.

| שיטה   | נתיב                 | תיאור                                                                                                             |
| ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/memory`        | הצגת זיכרונות — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`, עם עימוד באמצעות `offset/limit` או `page/limit`     |
| POST   | `/api/memory`        | יצירת זיכרון — גוף הבקשה מאומת באמצעות Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | אחזור זיכרון יחיד                                                                                                 |
| DELETE | `/api/memory/[id]`   | מחיקת זיכרון                                                                                                      |
| GET    | `/api/memory/health` | תקינות תת־מערכת הזיכרון (קישוריות למסד הנתונים, מנגנון ההטמעות, מצב האינדקס הווקטורי)                             |

**אימות:** הפעלת ניהול/מפתח API (`requireManagementAuth`). ערכי המנייה של `type`:‏ `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (ראו `MemoryType` בקובץ `src/lib/memory/types.ts`).

---

## שרת MCP

OmniRoute כולל שרת Model Context Protocol מובנה עם 3 תעבורות (stdio, SSE, streamable-http) וכלים מוגדרי־היקף. נקודות הקצה של לוח הבקרה שלהלן קוראות נתוני מצב/ביקורת ומתווכות את תעבורות ה-HTTP.

| שיטה | נתיב | תיאור |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | פעימת חיים, תעבורה, מצב מקוון, קריאה אחרונה, כלים מובילים, שיעור הצלחה ב-24 השעות האחרונות |
| GET | `/api/mcp/tools` | רשימת כלי MCP עם `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` |
| GET | `/api/mcp/sse` | פתיחת זרם SSE עבור תעבורת SSE (מחזיר `503` אם MCP מושבת או אם התעבורה אינה תואמת) |
| POST | `/api/mcp/sse` | שליחת מסגרת JSON-RPC בתעבורת SSE |
| GET | `/api/mcp/stream` | פתיחת צד ה-SSE של תעבורת Streamable HTTP (הודעות ביוזמת השרת) |
| POST | `/api/mcp/stream` | שליחת מסגרת JSON-RPC בתעבורת Streamable HTTP |
| DELETE | `/api/mcp/stream` | סיום הפעלת Streamable HTTP |
| GET | `/api/mcp/audit` | שאילתת יומן הביקורת — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | נתוני ביקורת מצטברים (סכומים כוללים, שיעור הצלחה, משך ממוצע, כלים מובילים) |

**אימות:** תעבורות `sse`/`stream` מכבדות את ממשק האימות הייעודי של MCP (מפתח API מסוג Bearer עם היקף `mcp`); הנתיבים `status`/`tools`/`audit*` ניתנים לקריאה מלוח הבקרה (לא נדרש אימות נוסף מעבר ליכולת להגיע למארח של לוח הבקרה).

> שתי תעבורות ה-HTTP מותנות ב-`settings.mcpEnabled` וב-`settings.mcpTransport` — אי־התאמה בתעבורה מחזירה `400`, ומצב שבו MCP מושבת מחזיר `503`.

---

## שרת A2A

OmniRoute חושף נקודת קצה מסוג A2A (סוכן-לסוכן) המבוססת על JSON-RPC 2.0, וכן מעטפת REST לצורכי בדיקה ולוח מחוונים.

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # אופציונלי, אלא אם OMNIROUTE_API_KEY מוגדר
Content-Type: application/json

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

שיטות נתמכות (כולן כפופות ל־`settings.a2aEnabled`):

| שיטה             | תיאור                                                         |
| ---------------- | ------------------------------------------------------------- |
| `message/send`   | הפעלת מיומנות סינכרונית; מחזירה `{task, artifacts, metadata}` |
| `message/stream` | הפעלת SSE בזרימה של אותה קבוצת מיומנויות                      |
| `tasks/get`      | אחזור משימה לפי `taskId`                                      |
| `tasks/cancel`   | ביטול משימה לפי `taskId`                                      |

מיומנויות מובנות: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`.

### כרטיס סוכן

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

מחזיר את כרטיס סוכן ה־A2A הציבורי (שם, תיאור, יכולות, קטלוג מיומנויות וסכמת אימות) — נשמר במטמון ציבורי למשך שעה. לא נדרש אימות.

### כלי עזר של REST

| שיטה | נתיב                         | תיאור                                                                                                            |
| ---- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| GET  | `/api/a2a/status`            | מצב הפעלת A2A + סטטיסטיקות משימות + תקציר כרטיס הסוכן השמור במטמון                                               |
| GET  | `/api/a2a/tasks`             | הצגת משימות — `?state=submitted\|working\|completed\|failed\|cancelled`, `?skill=`, `?limit=` (≤200), `?offset=` |
| POST | `/api/a2a/tasks`             | (לא ממומש ככלי עזר של REST — יש ליצור באמצעות JSON-RPC‏ `message/send`)                                          |
| GET  | `/api/a2a/tasks/[id]`        | אחזור משימה אחת                                                                                                  |
| POST | `/api/a2a/tasks/[id]/cancel` | ביטול משימה                                                                                                      |

**אימות:** כלי העזר של REST פועלים ללא אימות ניהולי (וניתנים לקריאה מלוח המחוונים); הנתיב `/a2a` של JSON-RPC משתמש ב־Bearer‏ `OMNIROUTE_API_KEY`, אם הוגדר.

---

## ענן, הערכות ובחינה

| מתודה | נתיב | תיאור |
| ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- |
| POST | `/api/cloud/auth` | אימות מפתח Bearer והחזרת חיבורי ספקים מוסווים וכינויי מודלים עבור לקוחות סנכרון ענן |
| POST | `/api/cloud/credentials/update` | עדכון פרטי גישה מוצפנים עבור ספק המסונכרן עם הענן |
| POST | `/api/cloud/model/resolve` | פתרון מזהה מודל לוגי לספק/מודל קונקרטי באמצעות טבלת הניתוב המקומית |
| GET | `/api/cloud/models/alias` | הצגת רשימת כינויי המודלים כפי שהם נחשפים לסנכרון ענן |
| GET | `/api/assess` | קריאת סיווגי ההערכה העדכניים ביותר (לפי ספק/מודל) |
| POST | `/api/assess` | הפעלת הערכה — גוף: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | הצגת רשימת חבילות ההערכה המובנות + ההרצות האחרונות |
| POST | `/api/evals` | הפעלת הרצת הערכה |
| POST | `/api/evals/suites` | יצירת חבילת הערכה מותאמת אישית — הגוף מאומת באמצעות `evalSuiteSaveSchema` |
| GET | `/api/evals/suites/[id]` | אחזור חבילת הערכה מותאמת אישית |

**אימות:** `/api/cloud/auth` מאמת מפתח Bearer ישירות ומחזיר את המפתח המוסווה ואת `projectId` של כל חיבור, רק עבור מפתח בעל ההרשאה `manage` / `admin`; הנתיבים האחרים תחת `/api/cloud/*`,‏ `/api/evals/*` ו-`/api/assess` דורשים הפעלת ניהול/מפתח API. בקשת POST אל `/api/assess` משתמשת ב-`validateBody` עם סכמת תחום מסוג איחוד מובחן.

---

## ניהול ACP (Agent Client Protocol)

כתהליכי־משנה. נקודות קצה אלו מנהלות זיהוי של סוכני ACP ורישום של סוכנים
מותאמים אישית.

| שיטה   | נתיב              | תיאור                                                                                                                                                     |
| ------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | הצגת כל סוכני ה-CLI המוכרים (מובנים + מותאמים אישית), כולל מצב התקנה, גרסה וקובץ בינארי                                                                   |
| POST   | `/api/acp/agents` | רישום סוכן ACP מותאם אישית או רענון המטמון — גוף הבקשה: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` או `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | הסרת סוכן ACP מותאם אישית — פרמטר שאילתה: `?id=<agentId>`                                                                                                 |

**דוגמה לתגובה** (`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
}
```

**אימות:** נדרשת הפעלת ניהול (קובץ cookie מסוג `auth_token` של לוח הבקרה) או
מפתח API בעל הרשאות ניהול.

לפרטים מלאים, ראו [מסגרת ACP](../frameworks/ACP.md).

---

## ניתוח נתונים ויכולת תצפית

נקודות קצה לניתוח נתונים בזמן אמת לצורך ניטור ניתוב, דחיסה וגיוון
ספקים. הן משמשות את הדפים `/dashboard/analytics/*`.

### ניתוח ניתוב אוטומטי

| שיטה | נתיב                                 | תיאור                                                                                       |
| ---- | ------------------------------------ | ------------------------------------------------------------------------------------------- |
| GET  | `/api/analytics/auto-routing`        | נתונים מצטברים על ניתוב אוטומטי: סך הקריאות, התפלגות אסטרטגיות, התפלגות רמות וספקים מובילים |
| GET  | `/api/analytics/auto-routing?days=7` | נתונים סטטיסטיים לפי חלון זמן (ברירת המחדל היא 24 שעות)                                     |

**דוגמה לתגובה**:

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

### ניתוח דחיסה

| שיטה | נתיב                         | תיאור                                                                                |
| ---- | ---------------------------- | ------------------------------------------------------------------------------------ |
| GET  | `/api/analytics/compression` | נתונים מצטברים על דחיסה: אסימונים שנחסכו, אחוז החיסכון, התפלגות מצבים ושימוש במנועים |

**דוגמה לתגובה**:

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

### מעקב אחר גיוון ספקים

| שיטה | נתיב                       | תיאור                                                                                        |
| ---- | -------------------------- | -------------------------------------------------------------------------------------------- |
| GET  | `/api/analytics/diversity` | מעקב אחר גיוון המבוסס על אנטרופיית שאנון: מניעת נקודות כשל יחידות באמצעות מדידת פיזור הספקים |

**דוגמה לתגובה**:

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

**אימות:** נדרשת הפעלת ניהול או מפתח API בעל הרשאות ניהול.

---

## פעולות מנהל מערכת

נקודות קצה למנהלי מערכת בלבד לצורך ניהול תפעולי.

| שיטה | נתיב                     | תיאור                                                                                         |
| ---- | ------------------------ | --------------------------------------------------------------------------------------------- |
| GET  | `/api/admin/concurrency` | קריאת מגבלות המקביליות הנוכחיות (גלובליות + לפי ספק)                                          |
| POST | `/api/admin/concurrency` | עדכון מגבלות המקביליות — גוף הבקשה: `{global?: number, perProvider?: Record<string, number>}` |

**אימות:** נדרשת הפעלת ניהול עם הרשאת מנהל מערכת.

---

## ניהול כלי CLI

ניהול כלי CLI המשתלבים עם OmniRoute‏ (antigravity, commandCode,
devin-cli וכו'). לרשימה המלאה, ראו [מידע על ספקים](./PROVIDER_REFERENCE.md).

| שיטה | נתיב                                    | תיאור                                                                                                                                                      |
| ---- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET  | `/api/cli-tools/all-statuses`           | הסטטוס של כל כלי ה-CLI (מותקן, גרסה, נראה לאחרונה)                                                                                                         |
| GET  | `/api/cli-tools/status`                 | פרטי הסטטוס של כלי CLI אחד (שאילתת `?tool=`)                                                                                                               |
| POST | `/api/cli-tools/apply`                  | כתיבת התצורה שנוצרה עבור כלי (`dryRun` מציג תצוגה מקדימה; `422` + `containerEphemeralTarget` בעת הרצה בקונטיינר; `migration` מציין קובץ YAML ישן של Codex) |
| GET  | `/api/cli-tools/backups`                | הצגת גיבויים של תצורות כלי CLI                                                                                                                             |
| POST | `/api/cli-tools/backups`                | יצירת גיבוי של כל תצורות כלי ה-CLI                                                                                                                         |
| POST | `/api/cli-tools/backups`                | שחזור: אותה נקודת קצה עם `{tool, backupId}` בגוף הבקשה משחזרת את הגיבוי הזה                                                                                |
| GET  | `/api/cli-tools/antigravity-mitm`       | סטטוס פרוקסי ה-MITM של Antigravity (כלי ה-CLI‏ "antigravity-mitm")                                                                                         |
| POST | `/api/cli-tools/antigravity-mitm/alias` | הגדרת כינויים עבור antigravity-mitm                                                                                                                        |

**אימות:** נדרשת הפעלת ניהול.

---

## מיומנויות סוכן

ניהול מיומנויות של סוכני AI (בדומה ל-GPTs המותאמים אישית של OpenAI, אך עבור סוכנים).

| שיטה   | נתיב                         | תיאור                                                                                            |
| ------ | ---------------------------- | ------------------------------------------------------------------------------------------------ |
| GET    | `/api/agent-skills`          | הצגת כל מיומנויות הסוכן (מובנות + מותאמות אישית)                                                 |
| GET    | `/api/agent-skills/[id]`     | קבלת מיומנות סוכן מסוימת                                                                         |
| POST   | `/api/agent-skills`          | יצירת מיומנות סוכן מותאמת אישית — גוף הבקשה: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | עדכון מיומנות סוכן מותאמת אישית                                                                  |
| DELETE | `/api/agent-skills/[id]`     | מחיקת מיומנות סוכן מותאמת אישית                                                                  |
| GET    | `/api/agent-skills/[id]/raw` | קבלת ההנחיה הגולמית + מטא-נתונים (ללא הפעלה)                                                     |
| POST   | `/api/agent-skills/generate` | יצירת מיומנות חדשה באמצעות AI מתיאור בשפה טבעית                                                  |

**אימות:** נדרשת הפעלת ניהול או מפתח API בעל הרשאות ניהול.

---

## ניהול מטמון

ניהול המטמון הסמנטי ומטמון ההסקה.

| שיטה   | נתיב                   | תיאור                                                                                                    |
| ------ | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | סקירת המטמון: מספר הרשומות הכולל, שיעור הפגיעות, גודל בדיסק                                              |
| GET    | `/api/cache/entries`   | הצגת רשומות המטמון (עם עימוד)                                                                            |
| DELETE | `/api/cache/entries`   | מחיקת רשומות מהמטמון (סינון לפי פרמטרים של השאילתה)                                                      |
| GET    | `/api/cache/stats`     | סטטיסטיקות מפורטות של המטמון (לפי ספק ולפי מודל)                                                         |
| GET    | `/api/cache/reasoning` | מצב מטמון ההסקה (להפעלה חוזרת של הסקה)                                                                   |
| DELETE | `/api/cache/reasoning` | ניקוי מטמון ההסקה — פרמטרים של השאילתה: `?toolCallId=<id>` (יחיד), `?provider=<p>` או ללא פרמטרים (הכול) |

**אימות:** נדרשת הפעלת ניהול.

---

## מערכת זיכרון

ניהול זיכרון מתמיד (FTS5 + הטמעות וקטוריות).

| שיטה   | נתיב               | תיאור                                                              |
| ------ | ------------------ | ------------------------------------------------------------------ |
| GET    | `/api/memory`      | הצגת רשומות הזיכרון (סינון לפי תחום, סוג ושאילתת חיפוש)            |
| POST   | `/api/memory`      | יצירת רשומת זיכרון חדשה — גוף: `{scope, type, content, metadata?}` |
| GET    | `/api/memory/[id]` | קבלת רשומת זיכרון מסוימת                                           |
| PUT    | `/api/memory/[id]` | עדכון רשומת זיכרון                                                 |
| DELETE | `/api/memory/[id]` | מחיקת רשומת זיכרון                                                 |
| GET    | `/api/memory?q=`   | חיפוש בזיכרון (FTS5 + וקטור) — הסטטיסטיקות כלולות באותה תגובה      |

**אימות:** נדרשת הפעלת ניהול או מפתח API בעל הרשאת ניהול.

---

## Webhooks

ניהול מינויים ל-webhook עבור אירועים.

| שיטה   | נתיב                            | תיאור                                                            |
| ------ | ------------------------------- | ---------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | הצגת כל המינויים ל-webhook                                       |
| POST   | `/api/webhooks`                 | יצירת מינוי ל-webhook — גוף: `{url, events[], secret?, active?}` |
| GET    | `/api/webhooks/[id]`            | קבלת מינוי מסוים ל-webhook                                       |
| PUT    | `/api/webhooks/[id]`            | עדכון מינוי ל-webhook                                            |
| DELETE | `/api/webhooks/[id]`            | מחיקת מינוי ל-webhook                                            |
| GET    | `/api/webhooks/[id]/deliveries` | הצגת היסטוריית המסירות של webhook (יומן הצלחות/כישלונות)         |
| POST   | `/api/webhooks/[id]/test`       | שליחת אירוע בדיקה ל-webhook                                      |

**אימות:** נדרשת הפעלת ניהול.

לסוגי האירועים המלאים, ראו [מסגרת Webhooks](../frameworks/WEBHOOKS.md).

---

## מסגרת המיומנויות

ניהול מיומנויות (מסגרת ההרחבות הסוכניות).

| שיטה   | נתיב                     | תיאור                                                                                  |
| ------ | ------------------------ | -------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | הצגת כל המיומנויות המותקנות (מובנות + מותאמות אישית)                                   |
| POST   | `/api/skills/install`    | התקנת מיומנות מנתיב מקומי או מכתובת URL                                                |
| DELETE | `/api/skills/[id]`       | הסרת התקנה של מיומנות                                                                  |
| PUT    | `/api/skills/[id]`       | הפעלה או השבתה של מיומנות — גוף: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | הפעלת מיומנות — גוף: `{skillName, apiKeyId, input?, sessionId?}`                       |
| GET    | `/api/skills/executions` | הצגת היסטוריית ההפעלות של כל המיומנויות (סינון לפי `?apiKeyId=`)                       |

**אימות:** נדרשת הפעלת ניהול או מפתח API בעל הרשאות ניהול.

לפרטים מלאים, ראו [מסגרת המיומנויות](../frameworks/SKILLS.md).

---

## תוספים

ניהול תוספי OmniRoute (הרחבות של צד שלישי).

| שיטה   | נתיב                               | תיאור                    |
| ------ | ---------------------------------- | ------------------------ |
| GET    | `/api/plugins`                     | הצגת התוספים המותקנים    |
| POST   | `/api/plugins/marketplace/install` | התקנת תוסף מזירת התוספים |
| DELETE | `/api/plugins/[name]`              | הסרת התקנה של תוסף       |
| POST   | `/api/plugins/[name]/activate`     | הפעלת תוסף               |
| POST   | `/api/plugins/[name]/deactivate`   | השבתת תוסף               |
| GET    | `/api/plugins/[name]/config`       | קבלת תצורת התוסף         |
| PUT    | `/api/plugins/[name]/config`       | עדכון תצורת התוסף        |

**אימות:** נדרשת הפעלת ניהול.

לפרטים מלאים, ראו [מסגרת התוספים](../frameworks/PLUGIN_SDK.md).

---

## ניתוב צללים

השוואת צללים / A-B בין ספקים **אינה ממשק REST עצמאי** — היא מוגדרת באמצעות ניתוב משולב (ראו [שילוב אוטומטי](../routing/AUTO-COMBO.md)). מדדי השוואה לכל שילוב מסופקים על ידי `GET /api/combos/metrics`.

---

## מנגנוני הגנה

בדיקת מנגנוני ההגנה בזמן ריצה (זיהוי PII, זיהוי הזרקת הנחיות, גישור ראייה). מנגנוני ההגנה פועלים בכל בקשה; ביטול הסכמה לכל קריאה מתבצע באמצעות כותרת הבקשה `x-omniroute-disabled-guardrails` — אין ממשק מתמשך להפעלה/השבתה.

| שיטה | נתיב                   | תיאור                                                                                        |
| ---- | ---------------------- | -------------------------------------------------------------------------------------------- |
| GET  | `/api/guardrails`      | הצגת מנגנוני ההגנה הרשומים והמצב שלהם (שם / מופעל / עדיפות)                                  |
| POST | `/api/guardrails/test` | הרצת ניסיון של צינור העיבוד שלפני הקריאה על קלט לדוגמה — גוף: `{input, disabledGuardrails?}` |

**אימות:** נדרשת הפעלת ניהול.

לפרטים מלאים, ראו [אבטחה > מנגנוני הגנה](../security/GUARDRAILS.md).

---

---

## אימות

ראו [אימות ניהולי](../guides/MANAGEMENT-AUTH.md) למידע על ארבע משפחות אמצעי ההזדהות (הפעלת לוח הבקרה, אסימון CLI מקומי, אסימון גישה `oma_live_…`, מפתח API בעל הרשאת ניהול) ועל ההבדלים בינן לבין מפתחות הסקה.

- נתיבי לוח הבקרה (`/dashboard/*`) משתמשים בקובץ Cookie בשם `auth_token`
- ההתחברות משתמשת בגיבוב הסיסמה השמור; אם אינו זמין, נעשה שימוש ב-`INITIAL_PASSWORD`
- ניתן להפעיל או להשבית את `requireLogin` באמצעות `/api/settings/require-login`
- נתיבי `/v1/*` דורשים באופן אופציונלי מפתח API מסוג Bearer כאשר `REQUIRE_API_KEY=true`
- "אסימון ניהול" / "מפתח API בעל הרשאת ניהול" במסמך עזר זה משמעו אחת מהמשפחות שבמדריך זה — ולא סוג נוסף ובלתי מוגדר של סוד

> **שינוי שובר תאימות (v3.8.0)** — הנתיבים `/api/v1/agents/tasks/*` ונקודות הקצה לניהול תקופת הצינון דורשים כעת **אימות ניהולי** (קובץ Cookie בשם `auth_token` של לוח הבקרה או מפתח API בעל הרשאת ניהול). לקוחות שקראו בעבר לנתיבים אלה ללא אימות יקבלו `401 Unauthorized`. ראו commit ‏`588a0333` (`fix(auth): require management auth for agent and cooldown APIs`).