Skip to content

Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors

177 KB
Raw Blame

API Reference (עברית)

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


🌐 שפות: 🇺🇸 אנגלית | 🇪🇹 אמהרית | 🇸🇦 ערבית | 🇦🇿 אזרית | 🇧🇬 בולגרית | 🇧🇩 בנגלית | 🇧🇦 בוסנית | 🇨🇿 צ׳כית | 🇩🇰 דנית | 🇩🇪 גרמנית | 🇬🇷 יוונית | 🇪🇸 ספרדית | 🇪🇪 אסטונית | 🇮🇷 פרסית | 🇫🇮 פינית | 🇫🇷 צרפתית | 🇮🇪 אירית | 🇮🇳 גוג׳ראטית | 🇳🇬 האוסה | 🇮🇱 עברית | 🇮🇳 הינדי | 🇭🇷 קרואטית | 🇭🇺 הונגרית | 🇦🇲 ארמנית | 🇮🇩 אינדונזית | 🇳🇬 איגבו | 🇮🇹 איטלקית | 🇯🇵 יפנית | 🇬🇪 גאורגית | 🇰🇭 חמרית | 🇮🇳 קנאדה | 🇰🇷 קוריאנית | 🇱🇹 ליטאית | 🇱🇻 לטבית | 🇮🇳 מלאיאלאם | 🇮🇳 מראטהית | 🇲🇾 מלאית | 🇲🇹 מלטית | 🇲🇲 בורמזית | 🇳🇵 נפאלית | 🇳🇱 הולנדית | 🇳🇴 נורווגית | 🇮🇳 אודיה | 🇮🇳 פנג׳אבית | 🇵🇭 פיליפינית | 🇵🇱 פולנית | 🇵🇹 פורטוגזית (פורטוגל) | 🇧🇷 פורטוגזית (ברזיל) | 🇷🇴 רומנית | 🇷🇺 רוסית | 🇱🇰 סינהלית | 🇸🇰 סלובקית | 🇸🇮 סלובנית | 🇷🇸 סרבית | 🇸🇪 שוודית | 🇰🇪 סווהילית | 🇮🇳 טמילית | 🇮🇳 טלוגו | 🇹🇭 תאית | 🇹🇷 טורקית | 🇺🇦 אוקראינית | 🇵🇰 אורדו | 🇺🇿 אוזבקית | 🇻🇳 וייטנאמית | 🇳🇬 יורובה | 🇨🇳 סינית (מפושטת) | 🇹🇼 סינית (מסורתית)

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

לפרוטוקול הממוקד התואם ל-OpenAI ולמטריצת היכולות של הספקים, ראו OPENAI_COMPATIBILITY.md.


תוכן עניינים


השלמות צ'אט

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 בקשה קיבוע בקשה למודל יחיד לחיבור ספק (חשבון) אחד לפי המזהה שלו — ראו קיבוע חשבון לכל בקשה
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:

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"}]}'
  • היכן למצוא את המזהה. פתחו את דף הספק בלוח הבקרה (לוח הבקרה → ספקים → ) ולחצו על תגית המזהה xxxxxxxx… בשורת חיבור — פעולה זו מעתיקה את מזהה החיבור המלא.
  • אילו בקשות מכבדות אותו. בקשות למודל יחיד (provider/model) בנקודות הקצה /v1/chat/completions,‏ /v1/messages ו-/v1/responses. שילובים מתעלמים מהכותרת: במקום זאת, הצמידו חשבון לכל שלב בשילוב באמצעות החיבור של השלב עצמו.
  • ההצמדה מחייבת, ואינה רק העדפה. נעשה שימוש בלעדי בחיבור המוצמד. כשל בתוך הבקשה מתעד את תקופת הצינון של החשבון, אך אינו עובר לחשבון מקביל של אותו ספק.
  • תקופת צינון ומכסה משחררות את ההצמדה. בזמן שהחיבור המוצמד נמצא בתקופת צינון, מיצה את המכסה או נחסם בידי מדיניות מכסה, בקשות מאוחרות יותר חוזרות לחיבורים האחרים של הספק, בדיוק כמו תעבורה שאינה מוצמדת.
  • מזהים לא מוכרים או מושבתים גורמים לכשל. מזהה שאינו נמצא במאגר הפעיל של הספק (נמחק, הושבת או שייך לספק אחר) אינו מותיר חשבון כשיר, ולכן הבקשה נכשלת במקום להיות מנותבת בשקט ליעד אחר.

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

{
  "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 מפורשת שאינה ריקה. גבול שינוי מסד הנתונים אוכף את שני השדות יחד ביצירת מפתח ובעדכונים חלקיים.

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:

{ "action": "renew", "generation": 1 }
{ "action": "release", "generation": 1, "reason": "OWNER_EXIT" }

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

{ "action": "status", "generation": 1 }
{
  "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.

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

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

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

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

{
  "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.


הטמעות

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:

{
  "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.
{
  "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 במקום לכפות המרה על הפריט. שדות הרחבה שאינם שדות קלט בבקשות מחרוזת/אסימון מדור קודם ממשיכים לעבור ללא שינוי.

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

יצירת תמונות

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 ואת OpenAI Images API.

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

OCR למסמכים

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:

{
  "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.


רשימת מודלים

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

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

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

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

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.

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

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

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:

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 כאשר מבקשים אותו במפורש. הבדיקה משתמשת בספק ובמודל לאחר הפענוח, לרבות כינויי ספקים, קידומות צמתים של ספקים תואמים וברירות מחדל של חיבורים. שילוב מדלג על יעדים מוסתרים ויכול להשתמש באפשרות גלויה מאותה קבוצה; כאשר לא נותר יעד בר-הרצה, מוחזר אותו קוד שגיאה. ביטול ההסתרה נכנס לתוקף בבקשה הבאה. עקיפות נראות לתמונות בלבד אינן מסתירות את מודל הצ'אט בעל אותו מזהה.

הגדרת מודל פרטנית זו נפרדת מ- רשימות ההתרה/חסימה לחשיפת מודלים, שמסננות את פרסום הקטלוג ואת המועמדים לניתוב אוטומטי, תוך שמירה על שיגור מפורש. הרשאות מודלים של מפתחות 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.


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

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}/... המתועדות להלן.

# דירוג מחדש (ספק ממרשם הענן, או צומת ספק תואם 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 [email protected] -F prompt="..." -F [email protected]

# יצירת וידאו / מוזיקה (מזהה מודל עם קידומת ספק)
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 מפורש בשורה מסונכרנת או בשורה שנוספה ידנית עדיין מקבל קדימות.

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

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

GET /v1/ws?handshake=1

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

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

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

# אותו מארח:פורט כמו 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 נפרד כדי להימנע משינוי תצורה קיימת):

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)
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) משתמש כדי להציג לבעל המפתח את ההוצאה שלו.

# תצורת טקסט (החוזה ההיסטורי — טקסט פשוט למסוף)
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 מחזיר מבנה מבחין, כך שהקורא לעולם אינו קורא שדה נתונים מתוך סירוב. במקרה של הצלחה:

{
  "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 עבור דריסות ברמת החיבור.

מטמון סמנטי

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

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

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

{
  "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]):

{ "cacheDefaultMode": "bypass" }

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

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

X-OmniRoute-No-Cache: true

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

נתיבי ניהול (/api/* למעט אימות/כניסה ציבוריים) אינם מורשים באמצעות מפתחות API רגילים להסקה. משפחות פרטי הזדהות, היקפים ודוגמאות curl: אימות לניהול.

אימות

נקודת קצה שיטה תיאור
/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 אימות מחמיר ואופציונלי של החיבור ורישום אטומי של מודל מותאם אישית, עם אימות ניהול; ראו אימות מודלים

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

צומתי Chat Completions מותאמים אישית מתאימים ביטול מפורש של הסקת מסקנות למערכת הקצה העורפית. בדיקת חיבור מוצלחת בוחרת אוטומטית פקדי תבנית צ'אט לכל מזהה מודל מדויק שהרשומה שלו ב-/models מוכיחה ערך owned_by מזוהה: vllm,‏ sglang או llamacpp. מעטפות שקופות תואמות OpenAI עשויות לשמר את רשומת המודל המקורית בתוך אובייקט openai מקונן; הזיהוי עוקב אחרי עד שלוש מעטפות כאלה. מודלים שהבעלות עליהם חסרה, אינה מוכרת או סותרת ממשיכים להשתמש בהתנהגות OpenAI רגילה. הזיהוי עושה שימוש חוזר בבקשת הקטלוג הקיימת, אינו יוצר אסימוני השלמה, ותוקפו מבוטל כאשר נקודת הקצה של החיבור משתנה.

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

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

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

בקשות המסווג במצב האוטומטי של Claude Code משביתות כברירת מחדל את החשיבה המקורית כאשר הן אינן כוללות בקרות חשיבה מפורשות. הזיהוי משתמש בסמן המערכת של המסווג בבקשות בפורמט Claude, ולא בשמות מודלים או במגבלות השלמה. בקרות מפורשות בגוף הבקשה, כותרות נתמכות של מאמץ/חשיבה, כללי ניתוב ומאמץ המודל שנקבע שומרים על העדיפות הקיימת שלהם. שני שלבי המסווג שומרים על ההנחיות, מגבלות ההשלמה, רצפי העצירה והכרעות ההרשאה האמיתיות מהשירות במעלה הזרם; השלב השני עדיין יכול להפיק את החשיבה הגלויה שהתבקשה כטקסט רגיל.

תהליכי OAuth

נקודת קצה שיטה תיאור
/api/oauth/[provider]/[action] שונות OAuth ייעודי לספק

ניתוב ותצורה

נקודת קצה שיטה תיאור
/api/models/alias GET/POST כינויים למודלים
/api/models/catalog GET כל המודלים לפי ספק + סוג
/api/combos* שונות ניהול שילובים
/api/keys* שונות ניהול מפתחות 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 צבירה מתגלגלת של זמני השהיה לפי ספק/מודל (ממוצע/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*, הוא דורש הרשאת ניהול (ראו אימות ניהול), ולא מפתח הסקה. שלחו רק את השדות שברצונכם לשנות; בקשה שאינה כוללת אף אחד מהם נדחית עם No valid fields to update. השדות המתקבלים מוגדרים על ידי updateKeyPermissionsSchema ב-src/shared/validation/schemas/keys.ts.

שדה סוג הערות
name מחרוזת, 1-200 תווים
isActive בוליאני
isBanned בוליאני
expiresAt תאריך ושעה בתקן ISO 8601 או null null מנקה את מועד התפוגה
modelAccessMode all | restricted allowedModels חייב להיות ריק כאשר המצב הוא all
allowedModels, blockedModels מערך של מחרוזות, עד 1000
allowedCombos מערך של מחרוזות, עד 500 קובע לאילו שילובים המפתח רשאי לקרוא; מודלים ישירים כפופים ל-modelAccessMode / allowedModels
connectionAccessMode all | restricted allowedConnections חייב להיות לא ריק כאשר המצב הוא restricted, וריק כאשר המצב הוא all
allowedConnections מערך של מזהי UUID, עד 100
allowAutoCombos בוליאני false דוחה בקשות למודלים מסוג auto/* עם מפתח זה; מפתחות שמעולם לא הגדירו אותו מורשים
catalogScope all | combos | models מה GET /v1/models מציג עבור מפתח זה (שילובים בלבד, מודלים בלבד או שניהם); אין בכך כדי לשנות למה המפתח רשאי לקרוא
forcedModel מחרוזת באורך של עד 300 תווים, או null מנתב בקשות צ'אט למודל/שילוב זה, בעדיפות על פני X-Route-Model ו-body.model; מגבלות המפתח עדיין חלות
noLog, autoResolve בוליאני
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 ראו עקיפת מטמון לפי מפתח
compressionEnabled בוליאני
codexServiceMode אחד ממצבי השירות של Codex
disableNonPublicModels boolean
allowUsageCommand boolean
usageLimitEnabled boolean
dailyUsageLimitUsd, weeklyUsageLimitUsd מספר >= 0 או null
chaosModeEnabled boolean
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; כל שינוי דורש את תחום אסימון הגישה 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_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.
/api/cache/stats GET/DELETE סטטיסטיקות מטמון / ניקוי
/api/modality-bridge/stats GET attempts בזיכרון, הצלחות/bridged, כישלונות, פגיעות במטמון, totalLatencyMs,‏ latencySamples,‏ averageLatencyMs המחושב לפי מספר הדגימות, וזמן השימוש האחרון (מתאפס בהפעלה מחדש; אימות ניהול)
/api/modality-bridge/video/runtime GET בדיקת loopback מהימן וקפדנית לפני אימות/בדיקת ניהול; זמינות וגרסאות מסוננות של FFmpeg/ffprobe (ללא אחסון)
/api/modality-bridge/video/extract POST מתווך בתים פנימי ומאומת דרך 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 מוסרים כל פרטי גישה שמורים, ולכן הם דורשים את סשן לוח הבקרה או את ה-CLI המקומי (או שההתחברות מושבתת). מפתחות API מכל היקף ואסימוני גישה מסוג oma_ מקבלים 403. על פעולות השחזור חלה אותה מגבלה: POST /api/db-backups/import (כולל dryRun=true),‏ POST /api/db-backups (שחזור לפי מזהה) ו-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/* שונות ניהול ענן

מנהרות

נקודת קצה שיטה תיאור
/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 מצב מגבלת הקצב לכל חשבון
/api/rate-limit GET תצורה גלובלית של מגבלת הקצב

כל ארבעת הנתיבים /api/resilience/* דורשים אימות ניהול (requireManagementAuth). לפירוט מלא של מפסק ספק לעומת תקופת צינון של חיבור לעומת נעילת מודל, ראו עמידות (מורחב).

הערכות

נקודת קצה שיטה תיאור
/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+)

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

{
  "provider": "claude-code"
}

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

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

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

GET /api/system/version

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

{
  "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 של גרסת ה-build הפועלת: nightly עבור גרסאות -nightly.*, ‏next עבור גרסאות קדם-הפצה אחרות (-rc.*,‏ -beta.*,‏ -alpha.*),‏ lts עבור גרסה יציבה מגרסה ראשית ישנה יותר מ-channels.latest, ובכל מקרה אחר latest. אותם כללים כמו ב-scripts/release/dist-tag.mjs, שבוחר את ה-dist-tag של npm בזמן הפרסום.
  • channels — הגרסה האחרונה שפורסמה בכל dist-tag, מתוך npm view omniroute dist-tags (עם חלופת HTTP לרישום), הנשמרת במטמון עם אותו TTL של 10 דקות כמו latest. הערך latest תמיד קיים (עם חזרה ל-latest ולאחר מכן ל-"unavailable"); הערכים next,‏ nightly ו-lts מופיעים רק כאשר ה-dist-tag המתאים קיים. בקשה עם Cache-Control: no-cache מרעננת את שתי הבדיקות.

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


תמלול אודיו

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

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

בקשה:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "[email protected]" \
  -F "model=openai/whisper-1"

תגובה:

{
  "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:

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

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

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

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

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

# כינוי לקטלוג בסגנון 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

דוגמה:

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. התייחסו אליהם כאפשרות תאימות, ולא כמצב האימות המוגדר כברירת מחדל.

טלמטריה

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

תגובה:

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

תקציב

# קבלת מצב התקציב עבור כל מפתחות ה-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 על פני המפתח כולו; כאשר מספר מגבלות תואמות לבקשה, המגבלה המחמירה ביותר גוברת.

# הצגת מגבלות הטוקנים של מפתח (כולל השימוש הנוכחי בחלון)
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


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

ניתן גם למפות שילובי ניתוב ברמה גבוהה יותר (שכבר סוכמו תחת /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 לגבי השינוי שאינו תואם לאחור.

# יצירת משימת ענן של 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; אותם שדות זמינים גם תחת לוח הבקרה → הגדרות → עמידות בפני תקלות.

# ניקוי נעילה של מודל יחיד
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 → "מצב זמן הריצה של העמידות בפני תקלות".


מיומנויות

מסגרת מיומנויות להרחבת 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

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.

כרטיס סוכן

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):

{
  "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.


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

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

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

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

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

{
  "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 נתונים מצטברים על דחיסה: אסימונים שנחסכו, אחוז החיסכון, התפלגות מצבים ושימוש במנועים

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

{
  "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 מעקב אחר גיוון המבוסס על אנטרופיית שאנון: מניעת נקודות כשל יחידות באמצעות מדידת פיזור הספקים

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

{
  "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 וכו'). לרשימה המלאה, ראו מידע על ספקים.

שיטה נתיב תיאור
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.


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

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

שיטה נתיב תיאור
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 בעל הרשאות ניהול.

לפרטים מלאים, ראו מסגרת המיומנויות.


תוספים

ניהול תוספי 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 עדכון תצורת התוסף

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

לפרטים מלאים, ראו מסגרת התוספים.


ניתוב צללים

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


מנגנוני הגנה

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

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

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

לפרטים מלאים, ראו אבטחה > מנגנוני הגנה.



אימות

ראו אימות ניהולי למידע על ארבע משפחות אמצעי ההזדהות (הפעלת לוח הבקרה, אסימון 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).