Files
OmniRoute/docs/i18n/ur/docs/reference/API_REFERENCE.md

226 KiB
Raw Permalink Blame History

API Reference (اردو)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇧🇦 bs · 🇨🇿 cs · 🇩🇰 da · 🇩🇪 de · 🇬🇷 el · 🇪🇸 es · 🇪🇪 et · 🇮🇷 fa · 🇫🇮 fi · 🇫🇷 fr · 🇮🇪 ga · 🇮🇳 gu · 🇳🇬 ha · 🇮🇱 he · 🇮🇳 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 · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW


🌐 زبانیں: 🇺🇸 English | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 Azərbaycan dili | 🇧🇬 Български | 🇧🇩 বাংলা | 🇧🇦 Bosanski | 🇨🇿 Čeština | 🇩🇰 Dansk | 🇩🇪 Deutsch | 🇬🇷 Ελληνικά | 🇪🇸 Español | 🇪🇪 Eesti | 🇮🇷 فارسی | 🇫🇮 Suomi | 🇫🇷 Français | 🇮🇪 Gaeilge | 🇮🇳 ગુજરાતી | 🇳🇬 Hausa | 🇮🇱 עברית | 🇮🇳 हिन्दी | 🇭🇷 Hrvatski | 🇭🇺 Magyar | 🇦🇲 Հայերեն | 🇮🇩 Bahasa Indonesia | 🇳🇬 Igbo | 🇮🇹 Italiano | 🇯🇵 日本語 | 🇬🇪 ქართული | 🇰🇭 ខ្មែរ | 🇮🇳 ಕನ್ನಡ | 🇰🇷 한국어 | 🇱🇹 Lietuvių | 🇱🇻 Latviešu | 🇮🇳 മലയാളം | 🇮🇳 मराठी | 🇲🇾 Bahasa Melayu | 🇲🇹 Malti | 🇲🇲 မြန်မာ | 🇳🇵 नेपाली | 🇳🇱 Nederlands | 🇳🇴 Norsk | 🇮🇳 ଓଡ଼ିଆ | 🇮🇳 ਪੰਜਾਬੀ | 🇵🇭 Filipino | 🇵🇱 Polski | 🇵🇹 Português (Portugal) | 🇧🇷 Português (Brasil) | 🇷🇴 Română | 🇷🇺 Русский | 🇱🇰 සිංහල | 🇸🇰 Slovenčina | 🇸🇮 Slovenščina | 🇷🇸 Српски | 🇸🇪 Svenska | 🇰🇪 Kiswahili | 🇮🇳 தமிழ் | 🇮🇳 తెలుగు | 🇹🇭 ไทย | 🇹🇷 Türkçe | 🇺🇦 Українська | 🇵🇰 اردو | 🇺🇿 Oʻzbekcha | 🇻🇳 Tiếng Việt | 🇳🇬 Yorùbá | 🇨🇳 中文 (简体) | 🇹🇼 中文 (繁體)

OmniRoute API کا بنیادی حوالہ۔ اس میں عوامی /v1 سطح اور سب سے زیادہ استعمال ہونے والے انتظامی اینڈ پوائنٹس شامل ہیں؛ مشین کے ذریعے پڑھی جانے والی docs/openapi.yaml فائل اور src/app/api/ کے تحت موجود روٹ ٹری مکمل ذرائع ہیں۔

OpenAI سے مطابقت رکھنے والے مخصوص پروٹوکول اور فراہم کنندہ کی صلاحیتوں کی میٹرکس کے لیے OPENAI_COMPATIBILITY.md دیکھیں۔

ہر تعیناتی /openapi.yaml پر اپنی اسپیک کی نقل فراہم کرتی ہے، جو بلڈ کے دوران docs/openapi.yaml سے تیار کی جاتی ہے۔ اس میں بلڈ کا ورژن اور متعلقہ سرور URL (./) شامل ہوتا ہے، تاکہ درخواستیں اسی میزبان پر بھیجی جائیں جس نے دستاویز فراہم کی ہو۔ ڈاؤن لوڈ کی گئی فائل درآمد کرنے والے ٹول کے پاس ایسا کوئی میزبان نہیں ہوتا، اس لیے بنیادی URL دستی طور پر مقرر کرنا ضروری ہے۔


فہرستِ مضامین


چیٹ تکمیلات

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
}

کسٹم ہیڈرز

Header Direction Description
X-OmniRoute-No-Cache درخواست کیش کو نظرانداز کرنے کے لیے true پر سیٹ کریں
x-omniroute-no-memory درخواست اس درخواست کے لیے میموری + اسکلز انجیکشن کو چھوڑنے کے لیے true پر سیٹ کریں (no-cache کی عکاسی کرتا ہے؛ فی کال ٹوکن/لاگت کے اضافی بوجھ سے بچاتا ہے)
X-OmniRoute-Progress درخواست پیش رفت کے ایونٹس کے لیے true پر سیٹ کریں
X-Session-Id درخواست بیرونی سیشن وابستگی کے لیے مستقل سیشن کلید
x_session_id درخواست انڈر اسکور والا متبادل بھی قبول کیا جاتا ہے (براہِ راست HTTP)
X-OmniRoute-Session-Id درخواست کال کرنے والے کی فراہم کردہ سیشن/گفتگو ٹیگ (میموری میں بھی شامل ہوتا ہے)۔ موجود ہونے پر اسے call_logs.session_tag میں فی سیشن لاگت کی نسبت کے لیے لفظ بہ لفظ محفوظ کیا جاتا ہے (#8249) — غیر موجود ہونے پر کبھی تخلیق نہیں کیا جاتا
Idempotency-Key درخواست ڈپلی کیشن کلید (5s ونڈو)
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"}]}'
  • آئی ڈی کہاں تلاش کریں۔ ڈیش بورڈ میں فراہم کنندہ کا صفحہ کھولیں (Dashboard → Providers → ) اور کنکشن کی قطار میں موجود xxxxxxxx… آئی ڈی چِپ پر کلک کریں — اس سے مکمل کنکشن آئی ڈی کاپی ہو جاتی ہے۔
  • کون سی درخواستیں اسے تسلیم کرتی ہیں۔ /v1/chat/completions، /v1/messages اور /v1/responses پر سنگل ماڈل درخواستیں (provider/model)۔ کومبو درخواستیں اس ہیڈر کو نظرانداز کرتی ہیں: ہر کومبو مرحلے کے لیے اس کے اپنے کنکشن کے ذریعے اکاؤنٹ پن کریں۔
  • پن سختی سے نافذ ہوتا ہے، یہ محض ترجیح نہیں۔ پن کیا گیا کنکشن خصوصی طور پر استعمال ہوتا ہے۔ درخواست کے اندر ناکامی اکاؤنٹ کے کول ڈاؤن کو ریکارڈ کرتی ہے، لیکن اسی فراہم کنندہ کے کسی ہم مرتبہ اکاؤنٹ پر منتقل نہیں ہوتی۔
  • کول ڈاؤن اور کوٹا پن ختم کر دیتے ہیں۔ جب پن کیا گیا کنکشن کول ڈاؤن میں ہو، کوٹا ختم ہو چکا ہو یا کوٹا پالیسی کی وجہ سے مسدود ہو، تو بعد کی درخواستیں فراہم کنندہ کے دوسرے کنکشنز پر واپس چلی جاتی ہیں، بالکل غیر پن شدہ ٹریفک کی طرح۔
  • نامعلوم یا غیر فعال آئی ڈیز ناکام ہو جاتی ہیں۔ ایسی آئی ڈی جو فراہم کنندہ کے فعال پول میں موجود نہ ہو (حذف شدہ، غیر فعال، یا کسی دوسرے فراہم کنندہ سے متعلق) کوئی اہل اکاؤنٹ باقی نہیں چھوڑتی، اس لیے درخواست خاموشی سے کہیں اور بھیجے جانے کے بجائے ناکام ہو جاتی ہے۔

Claude Code حسبِ ضرورت ہیڈرز ANTHROPIC_CUSTOM_HEADERS کے ذریعے بھیجتا ہے۔ اسے ~/.claude/settings.json کے env بلاک میں رکھیں، یا ہر پروجیکٹ کے لیے مختلف اکاؤنٹ پن کرنے کی خاطر پروجیکٹ کی سطح کی .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 ہوتی ہے (فیل اوپن)۔

کیش ہٹ کی لاگت کا مفہوم: سیمینٹک کیش کے HIT (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-base64url-characters>

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

کامیاب acquire، renew، اور release جوابات ٹائم اسٹیمپس، state، اور عین مثبت generation ظاہر کرتے ہیں، لیکن منتخب کنکشن یا اسناد کبھی ظاہر نہیں کرتے۔ Renew اور release JSON باڈی میں generation فراہم کرتے ہیں:

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

یہ اختیاری status ایکشن ایک ہی ڈیٹابیس ٹرانزیکشن میں غیر شفاف مالک، تصدیق شدہ منظم API کلید، اور عین فعال generation کے ذریعے محفوظ کیا جاتا ہے۔ displayName صرف ترتیب دیے گئے کنکشن کا تراشا ہوا نام ہوتا ہے؛ جب کوئی محفوظ ترتیب شدہ نام موجود نہ ہو تو یہ null ہوتا ہے۔ OmniRoute کبھی بھی ای میل یا تیار کردہ اکاؤنٹ شناخت کو متبادل کے طور پر استعمال نہیں کرتا۔ provider کی قدر غیر حساس ڈسپلے لیبل ہوتی ہے اور کبھی بھی تیار کردہ compatible-provider شناخت کنندہ نہیں ہوتی۔ اسناد، ٹوکنز، کوکیز، خام کنکشن یا API کلید کی IDs، مالک کے ہیشز، fencing secrets، اور اندرونی روٹنگ ڈیٹا خارج کر دیے جاتے ہیں۔

غلط کلید، غلط مالک، فرسودہ generation، غیر موجود، میعاد ختم شدہ، جاری کردہ، اور باطل شدہ lookups سب ایک ہی 409 LEASE_FENCE_STALE خرابی واپس کرتے ہیں، کنکشن میٹا ڈیٹا کے بغیر۔ جس کلائنٹ کو capacity-wait جواب موصول ہوا ہو، اس کے معائنے کے لیے کوئی فعال بائنڈنگ موجود نہیں ہوتی۔ جب روٹنگ کسی فعال لیز کو منتقل کرتی ہے تو وہی generation درست رہتا ہے اور status نئی بائنڈنگ کو ایٹمی طور پر واپس کرتا ہے، پرانے کو کبھی نہیں۔ موجودہ کلائنٹس میں کوئی تبدیلی نہیں آتی کیونکہ acquire، renew، release، اور waiting جوابات اپنی سابقہ شکلیں برقرار رکھتے ہیں۔

یہ سرور معاہدہ اسٹاک OpenAI Codex /status کو تبدیل نہیں کرتا۔ اسٹاک Codex فی الحال اپنے ماڈل فراہم کنندہ اور اندرونی تصدیق/اکاؤنٹ کی حالت رپورٹ کرتا ہے، لیکن من مانے حسبِ ضرورت فراہم کنندہ کے اکاؤنٹ میٹا ڈیٹا کو پیش نہیں کرتا؛ بعد کی کلائنٹ انٹیگریشن کو اس ایکشن کو کال کرنا اور یہ طے کرنا ہوگا کہ connection.displayName کو کیسے دکھایا جائے۔

اس کے بعد ہر منظم inference درخواست دونوں کنٹرول ہیڈرز فراہم کرتی ہے:

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

ہر معاون upstream کوشش سے فوراً پہلے عین مالک، generation، فعال کنکشن، اور تصدیق شدہ API کلید کی fencing کی جاتی ہے۔ مالک اور generation کو کسی دوسری کلید کے ساتھ دوبارہ استعمال کرنا ناکام ہو جاتا ہے، حتیٰ کہ جب وہ کلید اسی کنکشن کی اجازت دیتی ہو۔ خام مالکان کو محفوظ، لاگ، برقرار، request snapshot میں شامل، یا upstream کو فارورڈ نہیں کیا جاتا۔

عارضی مسابقت HTTP 429 کو Retry-After اور اس کے ساتھ واپس کرتی ہے:

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

اس جواب کا صرف یہ مطلب ہے کہ عام اہل سیٹ غیر خالی تھا اور ہر آزاد امیدوار کسی غیر متعلقہ فعال لیز کے پاس تھا۔ غیر معاون ماڈلز/فراہم کنندگان، پالیسی عدم مطابقت، cooldown، quota، health، اور اہلیت کی دیگر عام ناکامیاں اپنے موجودہ OmniRoute جوابات برقرار رکھتی ہیں۔

x-omniroute-compression

ہر درخواست کے لیے compression plan کو override کرتا ہے۔ سب سے زیادہ ترجیح — routing-combo override، فعال پروفائل، auto-trigger، اور panel Default سب پر غالب:

Value Effect
off اس درخواست کے لیے کوئی compression نہیں۔
default پینل سے اخذ کردہ Default پروفائل (فعال پروفائل کو نظر انداز کرتا ہے)۔ Lossy engines بند رہتے ہیں۔
safe صرف Dedup اور whitespace folding۔
allow-lossy اس درخواست کے لیے operator plan برقرار رکھتا ہے، بشمول summaries اور style rewrites۔
engine:<id> فعال ہونے پر ایک واحد engine، مثلاً engine:rtk۔ اس engine کے لیے فی درخواست opt-in۔
<combo> نام سے مماثل ایک نام زدہ combo، پہلے نام (case-insensitive) سے، پھر id سے۔

نوٹس:

  • نامعلوم قدروں کو نظر انداز کیا جاتا ہے (درخواست کبھی مسترد نہیں کی جاتی)؛ resolution معمول کی operator precedence کے مطابق جاری رہتی ہے۔
  • اگر متعدد combos کا نام ایک جیسا ہو تو deterministic match کے لیے combo id بھیجیں۔
  • جس combo کا نام off یا default ہو، اسے نام کے ذریعے منتخب نہیں کیا جا سکتا (ان keywords کی پہلے تشریح کی جاتی ہے)؛ ایسے combo کو اس کی id کے ذریعے reference کریں۔
  • master compression switch ایک سخت gate ہے: جب compression عالمی طور پر غیر فعال ہو تو یہ header اسے فعال نہیں کر سکتا۔

نافذ شدہ plan جواب کے header میں واپس echo کیا جاتا ہے:

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 کے embed/rerank/classify/segment ماڈلز پہلے ڈیش بورڈ کی jina-ai اسناد استعمال کرتے ہیں؛ JINA_AI_API_KEY صرف اس وقت متبادل کے طور پر استعمال ہوتا ہے جب ڈیش بورڈ کی کوئی کلید موجود نہ ہو۔ jina-reader کارڈ صرف Reader / r.jina.ai کے لیے ہے (POST /v1/web/fetch) اور ایمبیڈنگز یا rerank فراہم نہیں کرتا۔

رجسٹری کے وہ ماڈلز جو کثیر الوسائط معاونت ظاہر کرتے ہیں، زیادہ سے زیادہ 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) Jina کے مقامی EmbeddingsV5Request دستاویزات بھی قبول کرتا ہے اور انہیں جوں کا توں 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 } قدریں عوامی HTTPS URL، data: URI، یا خام base64 ہو سکتی ہیں۔ OmniRoute ان آبجیکٹس کو string میں تبدیل نہیں کرتا اور مقامی image URLs کو fetch نہیں کرتا — Jina خود عوامی میڈیا حاصل کرتا ہے۔ اضافی Jina فیلڈز (task، normalized، truncate، embedding_type) بھی فارورڈ کی جاتی ہیں۔ صرف متن والے Jina SKUs غیر متنی دستاویزات اب بھی مسترد کرتے ہیں۔

سیکیورٹی اور ٹرانسپورٹ کی حدود:

  • ریموٹ میڈیا URLs عوامی HTTPS ہونے چاہییں۔ معیاری {type,source:url} آئٹمز سرور کی جانب سے fetch کیے جاتے ہیں (ری ڈائریکٹ کی دوبارہ توثیق، ٹائم آؤٹ، سائز کی حدود، عوامی DNS، کنکشن پننگ) اور فراہم کنندہ کو کال کرنے سے پہلے inline کیے جاتے ہیں۔ Jina-native {image:"https://..."} آئٹمز اسی public-HTTPS جانچ کے بعد جوں کے توں فارورڈ کیے جاتے ہیں؛ Jina URL کو fetch کرتا ہے۔
  • Inline base64 میڈیا فی آئٹم 8 MiB decoded اور پوری درخواست میں 16 MiB decoded تک محدود ہے۔

فراہم کنندہ کے لیے ترجمہ (معیاری آئٹمز کبھی بھی بغیر تبدیلی کے فارورڈ نہیں کیے جاتے):

  • Jina کے کثیر الوسائط ماڈلز: ہر اعلیٰ سطحی آئٹم ایک modality-keyed آبجیکٹ (text / image / audio / video / pdf) بن جاتا ہے، جس میں inline میڈیا کے لیے data URIs استعمال ہوتی ہیں؛ ہر اعلیٰ سطحی آئٹم کے لیے ایک ویکٹر۔
  • Gemini Embedding 2 فیملی: ایک اعلیٰ سطحی array ایک واحد مقامی models/{model}:embedContent درخواست بن جاتی ہے، جس میں content.parts (text یا inline_data) شامل ہوتے ہیں۔
  • llama.cpp (llama-cpp/<model>، یعنی کوئی بھی ماڈل جسے مقامی سرور نے لوڈ کیا ہو): معیاری text آئٹمز سادہ strings بن جاتی ہیں، جبکہ image / audio / video ہر ایک الگ {"content": [part]} آبجیکٹ بن جاتا ہے، جس میں llama-server کے chat content parts (image_url، input_audio بمعہ format wav / mp3 / flac، input_video) اور inline data استعمال ہوتے ہیں؛ ہر اعلیٰ سطحی آئٹم کے لیے ایک ویکٹر۔ document معاونت یافتہ نہیں ہے۔ سرور کو --embedding --mmproj … کے ساتھ چلنا چاہیے؛ projector کے بغیر یہ خود میڈیا مسترد کر دیتا ہے۔
  • نامعلوم/متحرک ماڈلز جن کے پاس واضح modality metadata نہ ہو، ساخت یافتہ input کو 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"
}

غیر معاونت یافتہ model/modality امتزاج آئٹم کو زبردستی تبدیل کرنے کے بجائے HTTP 400 واپس کرتے ہیں۔ پرانی string/token درخواستوں میں موجود non-input extension فیلڈز بدستور بغیر تبدیلی کے آگے منتقل ہوتے رہتے ہیں۔

# تمام ایمبیڈنگ ماڈلز کی فہرست
GET /v1/embeddings

امیج جنریشن

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

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

دستیاب فراہم کنندگان میں OpenAI (GPT امیج 2)، xAI (Grok امیج)، Together AI (FLUX)، Fireworks AI، Nebius (FLUX)، Hyperbolic، NanoBanana، شامل ہیں۔OpenRouter ،ZenMux ، SD WebUI (مقامی)، ComfyUI (مقامی)۔

n data[] میں n تصاویر واپس کرتا ہے۔ وہ فراہم کنندگان جن کے upstream API فی کال ایک تصویر واپس کرتا ہے (Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik, NVIDIA NIM, Cloudflare Workers AI) پرواز میں زیادہ سے زیادہ 4 n علیحدہ اپ اسٹریم کالز حاصل کرتے ہیں۔ ایک فکسڈ seed کال انڈیکس (seed, seed + 1, …) کے ذریعہ آفسیٹ کیا جاتا ہے، لہذا تصاویر مختلف ہوتی ہیں لیکن دوبارہ پیدا کرنے کے قابل رہتی ہیں۔ n 10 پر محدود ہے۔ اگر کوئی کال ناکام ہوجاتی ہے تو درخواست مکمل طور پر ناکام ہوجاتی ہے۔ فین آؤٹ فارمیٹس کی فہرست open-sse/handlers/imageGeneration/fanOut.ts میں SINGLE_IMAGE_FANOUT_FORMATS ہے۔

ZenMux موجودہ API-key کنکشن کو دوبارہ استعمال کرتا ہے اور zenmux/ یا zm/ سابقے قبول کرتا ہے:

  • zenmux/openai/gpt-image-2 ZenMux کی OpenAI امیجز API استعمال کرتا ہے۔ اختیارات میں size, quality, n, output_format, output_compression, background, اور response_format شامل ہیں۔
  • دوسرے پبلشرز، جیسے zm/meta/muse-image-1.0، ZenMux کا ورٹیکس AI :predict اینڈ پوائنٹ استعمال کرتے ہیں۔ 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 کے ساتھ کی جا سکتی ہے۔

یہ انضمام ٹیکسٹ ٹو امیج جنریشن کو سپورٹ کرتا ہے، نہ کہ حوالہ سے تصویری ترمیم۔ ورٹیکس آؤٹ پٹ کو نارملائز کیا جاتا ہے data[].b64_json; response_format: "url" ایک upstream HTTPS URL یا ایک base64 ڈیٹا URL واپس کرتا ہے جب صرف تصویری بائٹس دستیاب ہوں۔ Empty/filtered آؤٹ پٹ خالی کامیابی کے بجائے ایک غلطی واپس کرتے ہیں۔ ماڈل تک رسائی ZenMux اکاؤنٹ پر منحصر ہے۔ ZenMux کی Vertex API اور OpenAI امیجز API دیکھیں۔

ایک Microsoft 365 Copilot سائن ان کنکشن Copilot کے بلٹ ان امیج ٹول کے ذریعے copilot-m365-web/m365-copilot-image خدمت کرتا ہے: ایک Copilot ٹرن فی امیج (n 1–4)، size صرف اورینٹیشن کو اسٹیئرنگ کرتا ہے، اور امیجز ان لائن واپس آتی ہیں (b64_json، یا response_format: "url" کے لیے ڈیٹا URL )۔ Microsoft 365 Copilot دیکھیں۔

# List all image models
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، provider/model prefix کے ذریعے OCR provider منتخب کرتا ہے؛ bare model id، مثلاً mistral-ocr-latest، اپنے registered provider سے resolve ہوتی ہے، اور اگر model نہ دیا جائے تو Mistral (mistral-ocr-latest) default ہوتا ہے۔ Registered providers (open-sse/config/ocrRegistry.ts):

Provider id Model id model value Notes
mistral mistral-ocr-latest mistral/mistral-ocr-latest (یا bare mistral-ocr-latest) Synchronous — response براہِ راست single upstream call سے واپس آتا ہے۔
azure-document-intelligence prebuilt-read azure-document-intelligence/prebuilt-read Asynchronous upstream (analyze + poll) — ذیل میں دیکھیں۔
vertex-deepseek-ocr deepseek-ocr-maas vertex-deepseek-ocr/deepseek-ocr-maas Synchronous، Vertex AI کے openapi/chat/completions partner endpoint کے ذریعے — auth/URL کے لیے ذیل میں دیکھیں۔

تینوں providers ایک ہی Mistral-shaped body میں response دیتے ہیں:

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

Azure Document Intelligence کا poll flow

Azure Document Intelligence کی analyze API asynchronous ہے: ابتدائی request body کے بجائے Operation-Location header واپس کرتی ہے، اور result کے لیے poll کرنا ضروری ہوتا ہے۔ Handler (open-sse/handlers/ocr.ts) ہر سیکنڈ بعد زیادہ سے زیادہ 30 attempts تک اس URL کو poll کرتا ہے، non-ok poll response یا "failed" status کی صورت میں فوراً ناکام ہو جاتا ہے (polling جاری نہیں رکھتا)، اور اگر attempt budget ختم ہونے کے بعد بھی operation جاری ہو تو 504 واپس کرتا ہے۔ حتمی Azure response کو واپس کرنے سے پہلے Mistral کے استعمال کردہ اسی pages/markdown shape میں normalize کیا جاتا ہے، اس لیے client code کو provider کے لحاظ سے الگ منطق کی ضرورت نہیں ہوتی۔

Vertex AI DeepSeek OCR کی auth اور endpoint resolution

vertex-deepseek-ocr وہی Vertex AI authentication دوبارہ استعمال کرتا ہے جسے OmniRoute پہلے ہی chat/image traffic کے لیے support کرتا ہے (open-sse/executors/vertex.ts): connection کی API key یا تو Service Account JSON credential ہوتی ہے (جسے JWT-bearer flow کے ذریعے مختصر مدت کے OAuth access token میں تبدیل کیا جاتا ہے) یا پہلے سے جاری کیا گیا OAuth access token ہوتا ہے، جسے جوں کا توں استعمال کیا جاتا ہے۔ Upstream endpoint URL، Vertex کے generic openapi/chat/completions partner endpoint کا ہوتا ہے، جو connection کے project اور region سے بنایا جاتا ہے — واضح providerSpecificData.project/providerSpecificData.region ہمیشہ ترجیح رکھتے ہیں؛ بصورتِ دیگر project، Service Account JSON کے project_id سے اخذ کیا جاتا ہے اور region کی default قدر us-central1 ہے۔ دونوں resolutions open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken، resolveVertexOcrBaseUrl) میں ہوتی ہیں، اور src/app/api/v1/ocr/route.ts میں handleOcr کو dispatch کرنے سے پہلے استعمال کی جاتی ہیں۔


ماڈلز کی فہرست

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

→ OpenAI فارمیٹ میں تمام چیٹ، ایمبیڈنگ، اور امیج ماڈلز + کومبو واپس کرتا ہے

ماڈل کی قیمتیں (pricing)

جب OmniRoute کو ماڈل کی قیمت معلوم ہو تو اندراج میں ایک pricing آبجیکٹ شامل ہوتا ہے۔ قیمت اس پرائسنگ ٹیبل سے آتی ہے جسے لاگت کا حساب کتاب استعمال کرتا ہے: پہلے سے شامل ڈیفالٹس، ہم وقت ساز قیمتیں، اور /api/pricing کے ذریعے متعین کردہ اووررائیڈز۔ یہ فہرست کی قیمتیں ہیں، اس لیے سبسکرپشن فراہم کنندگان کے لیے بھی فی ٹوکن قیمت دکھائی جاتی ہے۔

"pricing": {
  "prompt": "0.000005",
  "completion": "0.000025",
  "input_cache_read": "0.0000005",
  "input_cache_write": "0.00000625",
  "input": 5,
  "output": 25,
  "cached": 0.5,
  "cache_creation": 6.25
}
فیلڈز اکائی نوٹس
prompt, completion, input_cache_read, input_cache_write فی ٹوکن امریکی ڈالر، اعشاریہ اسٹرنگ OpenRouter کے ساتھ مطابقت رکھنے والا، کبھی exponent notation میں نہیں۔ کیش کے دونوں فیلڈز صرف اس وقت ظاہر ہوتے ہیں جب کیش کی قیمت موجود ہو۔
input, output, cached, cache_creation فی 1M ٹوکن امریکی ڈالر، عدد پہلے کے کیٹلاگ ورژنز کے فیلڈز، موجودہ کلائنٹس کے لیے برقرار رکھے گئے ہیں۔ جب پرائسنگ قطار میں یہ موجود ہوں تو reasoning اور long_context بھی ظاہر ہوتے ہیں۔
  • کومبو اپنے پہلے نظر آنے والے ہدف کی قیمت رکھتے ہیں۔ پہلے سے شامل auto/* کومبو درخواست کے وقت ہدف منتخب کرتے ہیں، اس لیے ان میں pricing نہیں ہوتا۔
  • مفت ماڈلز اس وقت "0" (اور 0) دکھاتے ہیں جب ان کی قیمت صفر ہو۔ جس ماڈل کی پرائسنگ قطار نہ ہو وہ بھی "0" دکھاتا ہے، اگر کیٹلاگ اسے مفت (free: true) نشان زد کرے یا پہلے سے شامل مفت-ماڈل کیٹلاگ میں درج ہو۔
  • نامعلوم قیمت: اندراج میں pricing کلید نہیں ہوتی۔
  • کریڈٹ کے حساب سے بل کرنے والے فراہم کنندگان (جیسے Kiro) فی ٹوکن کے بجائے فی درخواست بل کرتے ہیں۔ ان کے اندراجات میں پہلے سے موجود فی 1M عددی فیلڈز برقرار رہتے ہیں اور فی ٹوکن اسٹرنگ فیلڈز شامل نہیں ہوتے۔
  • ویریئنٹس (reasoning-effort ids، no-thinking aliases، discovery اور gateway mirrors) اس ماڈل کی قیمت نقل کرتے ہیں جس کی طرف وہ روٹ ہوتے ہیں۔
  • فیلڈز صرف بنیادی شرحیں رکھتے ہیں۔ طویل سیاق کے درجے (عددی long_context فیلڈ) اور سروس-ٹئیر ملٹی پلائرز (مثلاً Codex fast یا flex) prompt یا completion کو تبدیل نہیں کرتے۔
  • یہ آبجیکٹ ہر قسم کے توثیقی طریقے کے لیے یکساں ہے، بشمول x-api-key اور anthropic-version کے ساتھ Anthropic طرز کی درخواست (جواب بدستور { "object": "list", "data": [...] } رہتا ہے)۔ نفاذ: src/app/api/v1/models/catalogPricing.ts۔

ماڈل آئی ڈی کے سابقے (?prefix=)

زیادہ تر ماڈلز فراہم کنندہ کے سابقے کے تحت مشتہر کیے جاتے ہیں۔ آپ کو کون سا سابقہ ملے گا، یہ MODELS_CATALOG_PREFIX_MODE فیچر فلیگ سے کنٹرول ہوتا ہے، اور اسے ہر درخواست کے لیے کوئری پیرامیٹر کے ذریعے اووررائیڈ کیا جا سکتا ہے — یہ ایسے کلائنٹ کے لیے مفید ہے جو سب کے لیے سرور کی وسیع ترتیب تبدیل کیے بغیر صاف فہرست چاہتا ہو:

GET /v1/models?prefix=alias        # فی ماڈل ایک آئی ڈی — مختصر alias سابقہ
GET /v1/models?prefix=dual         # دونوں صورتیں (سرور ڈیفالٹ)
GET /v1/models?prefix=canonical    # صرف مکمل provider-id سابقہ
موڈ جاری کرتا ہے نوٹس
dual cc/claude-sonnet-4-6 اور claude/claude-sonnet-4-6 ڈیفالٹ۔ دونوں آئی ڈیز ایک ہی ماڈل کو روٹ کرتی ہیں؛ انہیں اس لیے برقرار رکھا گیا ہے کہ جن کلائنٹ کنفیگریشنز میں کسی ایک صورت کو ہارڈ کوڈ کیا گیا ہو، وہ کام کرتی رہیں۔ کیٹلاگ تقریباً دوگنا ہو جاتا ہے۔
alias cc/claude-sonnet-4-6 فی ماڈل ایک اندراج۔ جن فراہم کنندگان کا الگ alias نہیں ہے وہ بھی اپنا اندراج جاری کرتے ہیں، اس لیے کچھ ضائع نہیں ہوتا۔
canonical claude/claude-sonnet-4-6 مکمل provider-id سابقے کے تحت فی ماڈل ایک اندراج۔ جن فراہم کنندگان کا الگ alias نہیں ہے (مثلاً antigravity/…، agy/…) وہ یہاں بھی اپنی واحد آئی ڈی جاری کرتے ہیں، اس لیے کچھ ضائع نہیں ہوتا۔

dual-موڈ کے mirror کو کوئری پیرامیٹر کے بغیر بھی پہچانا جا سکتا ہے: اس میں بنیادی آئی ڈی کی طرف اشارہ کرنے والا parent فیلڈ ہوتا ہے۔

ماڈل منتخب کرنے والا انٹرفیس دکھانے والے کلائنٹس کو ?prefix=alias کی درخواست کرنی چاہیے — یہی OmniCopilot VS Code extension کرتا ہے۔

دریافت کے فلٹرز (?capability=, ?min_context=, ?kind=, ?q=)

GET /v1/models اختیاری دریافت کے فلٹرز قبول کرتا ہے۔ ان میں سے کوئی بھی نہ ہونے پر جواب غیر تبدیل رہتا ہے۔ یہ کال کرنے والے کو پہلے سے نظر آنے والے کیٹلاگ کو محدود کرتے ہیں (API-key کی اجازتیں پہلے لاگو ہوتی ہیں)، اور 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                           # id یا name پر کیس سے بے نیاز مطابقت
پیرامیٹر اقدار
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 کے ساتھ مسترد کر دیا جاتا ہے۔ یہ جانچ حل شدہ فراہم کنندہ اور ماڈل کو استعمال کرتی ہے، جس میں فراہم کنندہ کے عرف، مطابقت رکھنے والے فراہم کنندہ کے نوڈ سابقے، اور کنکشن کی طے شدہ اقدار بھی شامل ہیں۔ کومبو مخفی اہداف کو چھوڑ کر کسی ظاہر ساتھی کو استعمال کر سکتا ہے؛ جب کوئی قابلِ اجرا ہدف باقی نہ رہے تو یہی ایرر کوڈ لوٹایا جاتا ہے۔ مخفی حیثیت ختم کرنے کا اثر اگلی درخواست پر ہوتا ہے۔ صرف تصاویر کے لیے مرئیت کی اووررائیڈ اسی ID والے چیٹ ماڈل کو مخفی نہیں کرتی۔

یہ انفرادی ماڈل ترتیب ماڈل کی نمائش کی اجازت/ممانعت کی فہرستوں سے الگ ہے، جو واضح ڈسپیچ برقرار رکھتے ہوئے کیٹلاگ کے اشتہار اور خودکار روٹنگ کے امیدواروں کو فلٹر کرتی ہیں۔ API-key کی ماڈل اجازتیں بدستور الگ سے لاگو ہوتی ہیں۔ کیٹلاگ کے سابقہ موڈ کی طے شدہ قدر dual رہتی ہے۔

سوچ کے بغیر ماڈل کی اقسام

سوچنے کی صلاحیت رکھنے والے Claude ماڈلز کے لیے /v1/models ایک سوچ کے بغیر قسم بھی اشتہار کرتا ہے، جس کی ID کا سابقہ claude-3-omniroute-no-thinking/ ہوتا ہے:

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

اس ID کو منتخب کرنے پر (مثلاً Claude Code کی ایسی ترتیب میں جو ہمیشہ thinking بلاک شامل کرتی ہو) یہ حقیقی <provider>/<model> پر واپس حل ہو جاتی ہے، اور reasoning کو غیر فعال کر دیا جاتا ہے — /v1/messages پاتھ پر thinking:{type:"disabled"} کے ذریعے، یا /v1/chat/completions پاتھ پر reasoning/reasoning_effort فیلڈز حذف کر کے۔ یہ قسم صرف ان Claude-family ماڈلز کے لیے درج کی جاتی ہے جو thinking کو سپورٹ کرتے اور disabled کو قبول کرتے ہوں (لہٰذا، مثال کے طور پر، صرف adaptive ماڈلز جو disabled مسترد کرتے ہیں، خارج کر دیے جاتے ہیں)۔ آپریٹرز ModelSpec.noThinkingAlias کے ذریعے فی ماڈل اس قسم کو زبردستی فعال یا غیر فعال کر سکتے ہیں۔


فراہم کنندہ پلگ اِن مینی فیسٹ

GET /api/v1/provider-plugin-manifest

Bifrost، CLIProxyAPI، اور مستقبل کے sidecar routers کے ذریعے استعمال ہونے والا JSON-safe فراہم کنندہ پلگ اِن مینی فیسٹ واپس کرتا ہے۔ جواب TypeScript فراہم کنندہ رجسٹری سے تیار کیا جاتا ہے اور جان بوجھ کر OAuth کلائنٹ سیکرٹس، رن ٹائم ماحول کی resolution، executor functions، request headers، اور اکاؤنٹ ڈیٹا کو خارج کرتا ہے۔

یہ endpoint اس وقت استعمال کریں جب کوئی sidecar out-of-process چل رہا ہو اور open-sse/config/providerPluginManifestRegistry.ts کو براہِ راست import نہ کر سکتا ہو۔


ElevenLabs آڈیو جنریشن

OmniRoute میں اپنی ElevenLabs API key کے ساتھ ایک elevenlabs فراہم کنندہ کنکشن configure کریں۔ کلائنٹس اپنی OmniRoute key (Authorization: Bearer $OMNIROUTE_API_KEY) کے ذریعے تصدیق کرتے ہیں؛ gateway محفوظ شدہ فراہم کنندہ key کو xi-api-key کے طور پر فراہم کرتا ہے۔ ElevenLabs key کو gateway bearer token کے طور پر کبھی نہ بھیجیں۔

طریقہ راستہ جواب API key endpoint category
POST /v1/sound-generation مقامی آڈیو بائٹس elevenlabs
POST /v1/music مقامی آڈیو بائٹس music
POST /v1/music/stream اسٹریمنگ آڈیو بائٹس music
POST /v1/music/detailed مقامی multipart آڈیو اور کمپوزیشن پلان music
POST /v1/music/detailed/stream مقامی SSE میٹا ڈیٹا اور آڈیو چنکس music
POST /v1/music/plan JSON کمپوزیشن پلان music

یہ endpoints موجودہ /v1/audio/speech، /v1/audio/transcriptions، /v1/voices، /v1/text-to-speech/{voiceId} اور /v1/speech-to-text routes کی تکمیل کرتے ہیں۔ مقامی JSON فیلڈز اور query parameters جیسے output_format اور enable_logging محفوظ رہتے ہیں۔ /v1/music/detailed کے جوابات اپنی multipart boundaries برقرار رکھتے ہیں؛ انہیں multipart کے طور پر parse کریں۔ /v1/music/detailed/stream کمپوزیشن میٹا ڈیٹا اور SSE events میں base64 آڈیو چنکس کے ساتھ text/event-stream واپس کرتا ہے۔ تمام چھ routes CORS preflight کو سپورٹ کرتے ہیں۔

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

# ایک مختصر صوتی اثر۔ دورانیہ: 0.5 سے 30 سیکنڈ۔
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/sound-generation?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"A single soft bell chime","duration_seconds":1,"model_id":"eleven_text_to_sound_v2"}' \
  --output effect.mp3

# موسیقی کا دورانیہ ملی سیکنڈز میں ظاہر کیا جاتا ہے: 3000 سے 600000۔
curl --fail-with-body "$OMNIROUTE_BASE_URL/v1/music?output_format=mp3_44100_128" \
  -H "Authorization: Bearer $OMNIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Gentle instrumental piano","music_length_ms":10000,"force_instrumental":true,"model_id":"music_v1"}' \
  --output music.mp3

اضافی آڈیو کی ترسیل کے لیے اسی JSON body کے ساتھ /v1/music/stream استعمال کریں۔ Composition بالکل ایک prompt یا composition_plan قبول کرتا ہے؛ /v1/music/plan کے لیے prompt لازمی ہے اور یہ اختیاری طور پر source_composition_plan قبول کرتا ہے۔ مقامی schemas اضافی فراہم کنندہ فیلڈز کو محفوظ رکھتے ہیں تاکہ composition-plan ورژنز اور fine-tuning اختیارات ElevenLabs تک پہنچ سکیں۔

متحدہ /v1/music/generations endpoint elevenlabs/music_v1، elevenlabs/music_v2 اور elevenlabs/music_v2_5 بھی قبول کرتا ہے۔ فعال ElevenLabs کنکشن کے ساتھ، یہ ماڈلز music catalog کے ذریعے دستیاب ہوتے ہیں۔ یہ endpoint {"created":...,"data":[{"b64_json":"...","format":"mp3"}]} واپس کرتا ہے۔ اس کا duration فیلڈ سیکنڈز میں ہوتا ہے اور music_length_ms سے map ہوتا ہے؛ واضح طور پر فراہم کیا گیا music_length_ms ترجیح رکھتا ہے۔ instrumental، force_instrumental سے map ہوتا ہے، جبکہ مقامی فیلڈ کو ترجیح حاصل ہوتی ہے۔ اسٹریمنگ کے لیے مقامی streaming endpoints اور صرف composition plan سے چلنے والی درخواستوں کے لیے مقامی composition endpoint استعمال کریں۔

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

Endpoint، model، budget اور connection restrictions upstream call سے پہلے لاگو ہوتی ہیں۔ مقامی routes upstream status codes اور error bodies کو بغیر تبدیلی کے واپس کرتے ہیں، جن میں plan restriction کے لیے 402 اور quota limit کے لیے 429 بھی شامل ہیں۔ character-cost، song-id، request-id اور retry-after headers موجود ہونے پر محفوظ رہتے ہیں۔ مفت credit balance ہر music model، output format یا API feature تک رسائی کی ضمانت نہیں دیتا: ہر درخواست کے لیے entitlement کا فیصلہ ElevenLabs کرتا ہے۔ متحدہ endpoint، OmniRoute کے normalized error envelope میں error status codes محفوظ رکھتا ہے۔

Upstream contracts: صوتی اثرات، موسیقی کی composition اور streaming music کی تفصیلات۔


مطابقت کے اینڈ پوائنٹس

طریقہ راستہ فارمیٹ
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 (STT)
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 + Zod سے توثیق شدہ JSON باڈی (v1RerankSchema، v1ModerationSchema، v1AudioSpeechSchema وغیرہ، src/shared/validation/schemas.ts دیکھیں)۔ اسکیما کی ناکامی پر 4xx واپس کیا جاتا ہے۔

ایسے کلائنٹس کے لیے جو Authorization: Bearer ... شامل نہیں کر سکتے، OmniRoute URL میں API کیز بھی قبول کرتا ہے۔ اس کے لیے یا تو کوئری اسٹرنگ مطابقت (?token=...، ?apiKey=...، ?api_key=...، ?key=...) یا ذیل میں دستاویزی مخصوص /api/v1/vscode/{token}/... اینڈ پوائنٹس استعمال کیے جا سکتے ہیں۔

# دوبارہ درجہ بندی (کلاؤڈ رجسٹری فراہم کنندہ، یا "<prefix>/<model>" کے طور پر OpenAI-compatible provider node)
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina کی درجہ بندی (Foundation API credentials)
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

# ویڈیو / موسیقی کی تخلیق (فراہم کنندہ کے سابقہ والا ماڈل ID)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }

پرووائیڈر نوڈز کی دوبارہ درجہ بندی: POST /v1/rerank اوپن اے آئی سے ہم آہنگ پرووائیڈر نوڈز (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 یا کنکشن کے پن شدہ پراکسی کے ذریعے نہیں)۔ کسی بھی دوسرے ہوسٹ — LAN مشین یا Tailscale peer — پر موجود نوڈز صرف اسی وقت اہل ہوتے ہیں جب آپریٹر RERANK_REMOTE_PROVIDER_NODES فیچر فلیگ فعال کرے اور نوڈ کا بنیادی URL پرووائیڈر آؤٹ باؤنڈ URL پالیسی (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS) پر پورا اترے۔ میموری انجن کا دوبارہ درجہ بندی والا مرحلہ اس روٹ کو لوپ بیک کے ذریعے کال کرتا ہے، اس لیے یہی اصول Memory کی ترتیبات میں rerankProviderModel پر بھی لاگو ہوتا ہے۔

مقامی سرور کی ساختیں: نوڈ کو <base>/v1/rerank پر کال کیا جاتا ہے اور 404 کی صورت میں <base>/rerank پر (Infinity، TEI)۔ اپ اسٹریم باڈی میں Cohere/OpenAI املا (documents, return_documents) اور TEI املا (texts, return_text) دونوں شامل ہوتے ہیں، جبکہ اپ اسٹریم کے جواب کو Cohere envelope میں معمول پر لایا جاتا ہے: TEI کا سادہ [{index, score, text}]، باریک گیٹ ویز سے آنے والا {results: [{index, score}]}، اور Voyage طرز کا {data: [...]} — یہ سب کلائنٹ کو {results: [{index, relevance_score, document?}]} کی صورت میں واپس ملتے ہیں، اسکور کے لحاظ سے ترتیب دیے ہوئے اور top_n تک محدود۔

پرووائیڈر نوڈ کی دریافت: اوپن اے آئی سے ہم آہنگ پرووائیڈر نوڈ پر موجود ماڈلز GET /v1/models میں نوڈ کے سابقے کے تحت ظاہر ہوتے ہیں۔ وہ قطاریں جن میں endpoint کا کوئی میٹا ڈیٹا نہیں ہوتا (جو عموماً مقامی /v1/models فہرستوں میں ہوتا ہے)، نوڈ کے apiType کو اختیار کرتی ہیں؛ اس لیے embeddings نوڈ کے ماڈلز type: "embedding" اور rerank نوڈ کے ماڈلز type: "rerank" ہوتے ہیں، بجائے اس کے کہ انہیں بطورِ پیش فرض chat سمجھا جائے۔ تاہم، ہم وقت ساز یا دستی طور پر شامل کی گئی قطار میں موجود واضح supportedEndpoints کو ترجیح حاصل رہتی ہے۔

مخصوص پرووائیڈر روٹس

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

اگر پرووائیڈر سابقہ موجود نہ ہو تو اسے خودکار طور پر شامل کر دیا جاتا ہے۔ غیر مطابقت رکھنے والے ماڈلز 400 واپس کرتے ہیں۔


فائلز API

OpenAI کے ساتھ مطابقت رکھنے والا فائلز اینڈپوائنٹ، بیچ ان پٹ/آؤٹ پٹ اور فائل-مقصد اپ لوڈز کے لیے۔

طریقہ پاتھ وضاحت
POST /v1/files فائل اپ لوڈ کریں (ملٹی پارٹ: 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 خام فائل باڈی کو واپس اسٹریم کریں

تصدیق: Bearer API کلید — فائلیں getApiKeyRequestScope کے ذریعے فی API کلید محدود ہوتی ہیں۔ ایک کلید صرف اپنی فائلیں دیکھ، ڈاؤن لوڈ اور حذف کر سکتی ہے؛ بغیر کلید کے ڈیش بورڈ سیشن کو پورا انسٹنس پڑھنے کی اجازت ہوتی ہے؛ کسی مالک کے بغیر فائل (گمنام یا ڈیش بورڈ-سیشن اپ لوڈ) ہر غیر سیشن کالر کے لیے ممنوع ہوتی ہے۔ GET /v1/files کسی گمنام کالر — اور ایسی پیش کردہ کلید جو حل نہ ہو سکے — کو 401 کے ساتھ مسترد کرتا ہے، چاہے REQUIRE_API_KEY=false ہو، بجائے اس کے کہ ہر ٹیننٹ کی فائلوں کی فہرست دکھائے (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523)۔


بیچز 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 جاری بیچ منسوخ کریں

تصدیق: Bearer API کلید۔ بیچز فائلوں کے جیسے ہی تین طرفہ اصول کے تحت فی API کلید محدود ہوتے ہیں: صرف اپنی کلید، ڈیش بورڈ سیشن کے لیے پورا انسٹنس، اور null-owner ریکارڈز ہر غیر سیشن کالر کے لیے ممنوع ہیں (حاصل کرنا، حذف کرنا، منسوخ کرنا، اور تخلیق کے وقت input_file_id کی جانچ)۔ GET /v1/batches کسی گمنام کالر کو 401 کے ساتھ مسترد کرتا ہے، چاہے REQUIRE_API_KEY=false ہو۔


API تلاش کریں۔

Web/search فراہم کنندہ خلاصہ (Tavily, Brave, Exa, Serper, etc.)

طریقہ راستہ تفصیل
GET /v1/search ترتیب شدہ تلاش فراہم کنندگان کی + صلاحیتوں کی فہرست بنائیں
POST /v1/search ایک سرچ استفسار چلائیں — باڈی جس کی توثیق v1SearchSchema نے کی ہے، caching/coalescing کو سپورٹ کرتا ہے
GET /v1/search/analytics فی فراہم کنندہ hit/latency/cache اعدادوشمار

تصدیق: بیئرر API کلید (extractApiKey + isValidApiKey)۔ تلاش کی پالیسی enforceApiKeyPolicy کے ذریعے نافذ کی گئی۔

خودکار انتخاب: provider کے بغیر، کنفیگرڈ کنکشن کے ساتھ سب سے سستا فراہم کنندہ پہلے چلتا ہے اور اگلا سب سے سستا فیل اوور ہے۔ مفت آخری ریزورٹ فراہم کرنے والے (duckduckgo-free) صرف اس وقت استعمال ہوتے ہیں جب کوئی اور چیز کنفیگر نہ ہو۔ ایک سیلف ہوسٹڈ SearXNG شمار کنفیگر ہونے کے بعد ہوتا ہے جب اس کا کنکشن اصلی baseUrl (کیٹلاگ ڈیفالٹ http://localhost:8888/search نہیں) کو اسٹور کر لیتا ہے: اس کے بعد یہ کیڈ والوں سے آگے $0 فراہم کنندہ کے طور پر درجہ بندی کرتا ہے، جس میں فیل اوور کے طور پر سب سے سستا کلید فراہم کنندہ ہوتا ہے، بشمول جب SearXNG جواب دیتا ہے 400, 401, 04gval 40g یا 40gval3 نہیں ہے http(s) baseUrl URL کلاؤڈ میٹا ڈیٹا ایڈریس پر پوائنٹس کو شمار نہیں کیا جاتا ہے۔ ایک SearXNG کنکشن جو ٹوکن کو اسٹور کرتا ہے اس طرح صرف https:// یا لوپ بیک http:// پر ہوتا ہے۔ دور دراز کے سادہ http:// پر یہ کبھی بھی ناکام نہیں ہوتا اور آخری حربہ رہتا ہے، صرف اس وقت استعمال ہوتا ہے جب کوئی اور فراہم کنندہ کنفیگر نہ ہو یا جب نام سے درخواست کی گئی ہو، لہذا یہ ان دو صورتوں میں ٹوکن کو کلیئر ٹیکسٹ میں بھیجتا ہے۔

Exa اور Tavily provider_options

Exa اور Tavily نام کی جگہ والے بیگ سے فراہم کنندہ کے مخصوص فیلڈز کو پڑھیں: provider_options.exa (یا provider_options["exa-search"]) اور provider_options.tavily (یا provider_options["tavily-search"])۔ صرف نیچے کی چابیاں آگے بھیجی جاتی ہیں۔ ہر ایک کو open-sse/handlers/search/providerOptionsPassthrough.ts میں اس کے اپنے Zod اسکیما کے خلاف چیک کیا جاتا ہے، اور غلط قسم والی کلید چھوڑ دی جاتی ہے۔ کسی بھی دوسری کلید کو نظر انداز کر دیا جاتا ہے، بشمول auth، base URL، stream اور outputSchema۔ دوسرے فراہم کنندگان (cx, depth, ...) کے ذریعے استعمال ہونے والی فلیٹ کیز پہلے کی طرح کام کرتی ہیں۔

فراہم کرنے والا ٹاپ لیول فیلڈز نیسٹڈ
Exa type, category, userLocation, moderation, additionalQueries, objective, systemPrompt, compliance (فلیٹ پرائمیٹو) , startPublishedDate, endPublishedDate contents.{text, highlights, summary, extras, livecrawlTimeout, maxAgeHours} پہلے سے طے شدہ { text: true, highlights: true } پر ضم ہوگیا۔
تاویلی 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") کو بھی قبول کرتا ہے۔

فائر کرول تلاش کی لاگت 10 واپس کیے گئے نتائج کے فی شروع شدہ بلاک میں، $0.002 (2 کریڈٹ) ایک بلاک اور کم از کم ایک بلاک فی کال ( فائرکرول بلنگ ): 11 نتائج کی لاگت $0.004 ہے۔

عام time_range اب دونوں فراہم کنندگان تک پہنچ جاتا ہے: Exa کو startPublishedDate (ISO ٹائم اسٹیمپ) اور Tavily کو start_date (YYYY-MM-DD) ملتا ہے۔ provider_options میں ایک واضح تاریخ میپ شدہ کو اوور رائیڈ کرتی ہے۔

Exa نتائج میں id، highlights (ہر خاص بات، نہ صرف snippet کے طور پر استعمال ہونے والی پہلی چیز)، highlight_scores، summary، subpages، entities اور extras provider_raw میں رکھا جاتا ہے۔ Tavily کے نتائج images اور favicon رکھتے ہیں۔

لنک اپ تلاش کی قیمت depth fast اور standard کے لیے $0.005 اور deep ( Linkup pricing ) کے لیے $0.05 ریکارڈ کی گئی ہے، چاہے depth provider_options سے آیا ہو یا کنکشن کی ترتیبات سے۔

Exa type: "lite" (Exa 3.0) فیلڈز کے ایک چھوٹے سیٹ کو قبول کرتا ہے اور جب کوئی دوسرا فیلڈ سیٹ کیا جاتا ہے تو پوری درخواست کو مسترد کر دیتا ہے۔ لائٹ کے لیے، additionalQueries، systemPrompt اور text اور highlights کے علاوہ ہر contents کلید کال سے پہلے چھوڑ دی جاتی ہے۔ فرسودہ subpages، subpageTarget، highlights.numSentences اور highlights.highlightsPerUrl مزید آگے نہیں بھیجے جاتے ہیں۔

لاگت کا حساب کتاب فلیٹ رجسٹری costPerQuery ہے، Exa کے علاوہ، جو Exa کی اپنی قیمتوں کی پیروی کرتا ہے: $0.007 فی کال auto (اور لیگیسی fast) کے لیے یا $0.004 lite (اور لیگیسی instant) کے لیے، جس میں 10 نتائج شامل ہیں۔ ہر مزید نتیجے کے لیے $0.001؛ اور $0.001 فی لوٹا ہوا نتیجہ جب contents.summary سیٹ ہو۔ Tavily کو search_depth basic، fast اور ultra-fast کے لیے 1 کریڈٹ ($0.008) اور advanced ( Tavily API کریڈٹس ) کے لیے 2 کریڈٹ ($0.016) پر ریکارڈ کیا گیا ہے۔ auto_parameters: true کے ساتھ ایک کال جسے Tavily ایڈوانس میں اپ گریڈ کرتا ہے اب بھی 1 کریڈٹ پر ریکارڈ کیا جاتا ہے۔


Web Fetch API

کنفیگر کردہ ویب-فچ فراہم کنندہ (Firecrawl، Jina Reader، Tavily Extract، TinyFish Fetch، Nimble Extract، Parallel Extract) کے ذریعے URL سے مواد اخذ کریں۔

Parallel Extract (parallel-search، وہی API key جو Parallel Search کے لیے ہے) صرف Markdown واپس کرتا ہے — کوئی بھی دوسری format ایک 400 ہے — اور مواد کو 100,000 حروف تک محدود کرتا ہے۔ جب ہدف صفحہ خود اخذ نہ کیا جا سکے، تو upstream اسے HTTP 200 کے اندر رپورٹ کرتا ہے؛ OmniRoute اسے ایک مقررہ پیغام کے ساتھ 422 کے طور پر ظاہر کرتا ہے۔

طریقہ پاتھ وضاحت
POST /v1/web/fetch URL کو fetch/scrape کریں — body کی توثیق v1WebFetchSchema کے ذریعے ہوتی ہے

Auth: Bearer API key (extractApiKey + isValidApiKey)۔ پالیسی enforceApiKeyPolicy کے ذریعے نافذ ہوتی ہے۔

Quota-aware fallback (#8297): جب کوئی واضح provider نہ دیا جائے، تو pool (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search → parallel-search) کو مقررہ ترجیحی ترتیب (fill-first) میں آزمایا جاتا ہے — rate-limited لیکن configured فراہم کنندہ کو request کو short-circuit کرنے کے بجائے چھوڑ دیا جاتا ہے، اور retryable/quota upstream failure (HTTP 429 ہمیشہ؛ Firecrawl/Tavily/TinyFish کے quota-style free tiers کے لیے 402/403 — Jina Reader کے لیے نہیں، اور عام 400 bad request کے لیے کبھی نہیں) request کے وقت اگلے غیر آزمودہ credentialed فراہم کنندہ تک پہنچتا ہے۔ جب pool کا ہر فراہم کنندہ exhausted ہو جائے، تو endpoint پچھلے عمومی 400 کے بجائے ایک واحد 429 (Retry-After header کے ساتھ) واپس کرتا ہے۔ جب واضح provider کی درخواست کی جائے، تو کوئی خاموش fallback نہیں ہوتا — rate-limited یا ناکام واضح فراہم کنندہ اپنی خرابی ظاہر کرتا ہے (429 اگر rate-limited ہو، ورنہ upstream status)۔


WebSocket Streaming

GET /v1/ws?handshake=1

WebSocket upgrade handshake کی توثیق کرتا ہے اور wire protocol کے مثال کے پیغامات (request، cancel) واپس کرتا ہے۔ اصل WS frames bundled WS server کے ذریعے Next.js route table کے باہر handle کیے جاتے ہیں۔

Auth: handshake کے دوران Bearer API key۔

Responses API over WebSocket (صرف codex)

# HTTP API جیسا ہی host:port (default 20128)؛ connection کو upgrade کریں:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (یا: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# پہلا frame لازماً response.create ہونا چاہیے:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }

Responses-API-over-WebSocket proxy صرف codex (ChatGPT backend) کے لیے منسلک ہے۔ یہ API/dashboard کے اسی port پر paths /v1/responses, /responses، اور /api/v1/responses پر سنتا ہے۔ پہلے response.create frame پر یہ internal codex-responses-ws bridge کے ذریعے authentication اور تیاری کرتا ہے، ایک codex OAuth connection منتخب کرتا ہے، اور wreq-js transport کے ذریعے wss://chatgpt.com/backend-api/codex/responses تک tunnel کرتا ہے۔ Non-codex models مسترد کیے جاتے ہیں (codex_ws_provider_required)۔ Quota-share routing کے لیے model: "qtSd/<group>/codex/<model>" استعمال کریں۔ اسے app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts میں نافذ کیا گیا ہے۔

Auth: handshake کے دوران Bearer API key۔ bundled HTTP server (server-ws.mjs) فعال entrypoint ہونا چاہیے (جب app/server-ws.mjs موجود ہو تو یہ default طور پر یہی ہوتا ہے)۔

Model id: bare ChatGPT id استعمال کریں (codex/ prefix کے بغیر)

OpenAI Codex CLI client-side طور پر model name کی توثیق کرتا ہے جب supports_websockets = true ہو، اور provider-prefixed ids جیسے codex/gpt-5.5 کو مسترد کرتا ہے (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account)۔ bare id بھیجیں (مثلاً gpt-5.5)۔ OmniRoute کا bridge صرف codex کے لیے ہے، اس لیے یہ tunnel کرنے سے پہلے bare id کو codex model کے طور پر دوبارہ resolve کرتا ہے (resolveCodexWsModelInfo) — اگرچہ HTTP کے ذریعے bare gpt-5.5 بصورت دیگر کسی دوسرے فراہم کنندہ کو route ہو گا۔

OpenAI Codex CLI کو کنفیگر کرنا

OmniRoute کی طرف Codex CLI کی سمت متعین کرنے کے لیے ~/.codex/config.toml میں WebSocket support کے ساتھ custom provider شامل کریں (موجودہ config کو متاثر ہونے سے بچانے کے لیے علیحدہ CODEX_HOME استعمال کریں):

model = "gpt-5.5"                 # bare id — "codex/gpt-5.5" نہیں
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # آخری slash کے بغیر؛ WS URL اسی سے اخذ ہوتا ہے (production میں https/wss استعمال کریں)
wire_api = "responses"                    # Feb 2026 سے صرف یہی supported value ہے
supports_websockets = true                # Responses-over-WS transport فعال کرتا ہے
env_key = "OMNIROUTE_API_KEY"             # OmniRoute API key (Bearer) رکھتا ہے
export OMNIROUTE_API_KEY=sk-...           # OmniRoute API key (اگر REQUIRE_API_KEY=false ہو تو کوئی بھی key)
codex exec "Responda apenas: PONG"

CLI base_url + /responses کو WebSocket میں upgrade کرتا ہے اور OmniRoute اسے منتخب کردہ codex OAuth connection تک tunnel کرتا ہے۔ مقامی server کے خلاف end-to-end توثیق کی گئی ہے: ChatGPT codex.rate_limits + response.created واپس کرتا ہے اور completion کو stream کرتا ہے۔


کوٹے اور مسائل کی رپورٹنگ

طریقہ راستہ تفصیل
GET /v1/quotas/check رجسٹرڈ کلید جاری کرنے سے پہلے provider + accountId کے کوٹے کی پیشگی توثیق کریں
POST /v1/issues/report کوٹے/کلید جاری کرنے کی ناکامی کی GitHub کو رپورٹ کریں (GITHUB_ISSUES_REPO + ٹوکن درکار ہے)

توثیق: Bearer API کلید (isAuthenticated)۔

کوٹا سیشن کی بحالی (اختیاری)

ایک non-streaming POST /v1/chat/completions یا POST /v1/responses درخواست جو حتمی کوٹا خرابی (402/429/503 جس کے body میں کوٹا یا کریڈٹس ختم ہونے کا ذکر ہو) کے ساتھ ناکام ہو، اسے خرابی واپس کرنے کے بجائے بعد میں دوبارہ چلانے کے لیے محفوظ کیا جا سکتا ہے۔ کالر ہر درخواست کے لیے درج ذیل تین headers کے ذریعے اس خصوصیت کو فعال کرتا ہے:

Header قدر
x-omniroute-quota-recovery auto
x-omniroute-session سیشن ID، [A-Za-z0-9._:-]{1,128}
x-omniroute-recovery-turn سیشن کے اندر منفرد turn ID (وہی اصول)

صرف stream: false والے turns جن میں tools، tool history یا previous_response_id نہ ہو، اور x-omniroute-connection pin نہ ہو، اہل ہیں، اور STORAGE_ENCRYPTION_KEY متعین ہونا چاہیے (درخواست کو زیادہ سے زیادہ 24 گھنٹوں کے لیے encrypted حالت میں محفوظ کیا جاتا ہے)۔ اس کے بعد جواب 202 ہوتا ہے جس میں recovery.poll شامل ہوتا ہے؛ poll کے لیے GET /v1/quota-recoveries/{id} استعمال کریں (202 زیر التوا حالت میں، تکمیل کے بعد بحال شدہ body کے ساتھ 200) یا DELETE کے ذریعے منسوخ کریں۔ Tickets صرف اس API کلید کو دکھائی دیتے ہیں جس نے انہیں بنایا ہو۔ ایسی replay جس کا نتیجہ غیر یقینی ہو، دو مرتبہ بھیجے جانے کے بجائے needs_confirmation حالت میں ختم ہوتی ہے۔ ماخذ: src/lib/quota/quotaSessionRecovery.ts۔


سیلف سروس کا استعمال (/api/usage/om-usage)

کوئی بھی API کلید پڑھ سکتی ہے۔** اس کا اپنا** استعمال اور کوٹہ — کوئی انتظامی سند نہیں ہے۔ یہ وہ اختتامی نقطہ ہے جو ایک کلائنٹ (CLI، OmniCopilot پینل) کلیدی ہولڈر کو ان کا خرچ دکھانے کے لیے استعمال کرتا ہے۔

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

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

چابی ہونی چاہیے۔allowUsageCommand فعال (بذریعہ ڈیفالٹ — ڈیش بورڈ کا API کلید مینیجر اسے فی کلید ٹوگل کرتا ہے)۔ اس کے بغیر اختتامی نقطہ جواب دیتا ہے 403۔

?format=json امتیازی شکل لوٹاتا ہے لہذا کال کرنے والا کبھی بھی انکار پر ڈیٹا فیلڈ نہیں پڑھتا ہے۔ کامیابی پر:

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

انکار پر (401 bad key / 403 اجازت نہیں ہے) وہی راستہ { "allowed": false, "error": { "message": "…" } } — لوٹاتا ہے ایک موجودہ لیکن خالی personal/provider (کلید کی اجازت ہے، ابھی تک کچھ نہیں سیکھا) انکار سے ایک مختلف حالت ہے، اور صرف JSON فارم ان کو ممتاز کرتا ہے۔

تصدیق: کال کرنے والے کی اپنی بیئرر API کلید، isValidApiKey — کے ساتھ تصدیق شدہ یہ not انتظامی سطح (/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 فی کنکشن (یا سرور ڈیفالٹس) میں محفوظ
بنیادی صارف انٹرایکٹو CLIs، ٹرمینل پرامپٹس، انسانی آپریٹرز پروگرامیٹک انضمام، ڈیش بورڈز، تجزیات، بلنگ ٹریکرز

کٹ آف ایڈجسٹمنٹ فارمولہ

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% کٹ آف پالیسی کے ذریعے محفوظ ہے۔ کال کرنے والے کے پاس 75% قابل استعمال ہیڈ روم میں سے صرف 15% باقی ہے اس سے پہلے کہ روٹر اس کنکشن پر روٹنگ بند کر دے۔ اسکیلنگ کنکشن سگنلز کی تھکن کو یقینی بناتی ہے (0% left) بالکل اسی وقت جب روٹنگ بند ہو جائے گی۔
  • JSON خام اقدار کو کیوں محفوظ رکھتا ہے: JSON پے لوڈ عین فراہم کنندہ کا اسنیپ شاٹ (UsageSnapshot) واپس کرتا ہے لہذا بیرونی ٹولز کو سرور کی طرف نقصان دہ اسکیلنگ کے بغیر زمینی سچائی کے اپ اسٹریم استعمال اور کنکشن کی سطح کے quotaWindowThresholds تک رسائی حاصل ہوتی ہے۔

کنزیومر مائیگریشن گائیڈنس

اگر ایک بیرونی انضمام (جیسے ایڈیٹر پلگ ان یا ایجنٹ ایکسٹینشن) نے پہلے ٹیکسٹ اینڈ پوائنٹ (NN% left) کو سکریپ کیا اور استعمال شدہ فیصد کو 100 - NN کے طور پر شمار کیا تو ?format=json میں منتقل ہونے کا مطلب ہے:

  • خام JSON اقدار کو پڑھنے سے ظاہر ہوگا۔** اصل upstream کی کھپت** (اوپر کی مثال میں 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 جواب کیش سے فراہم کرتا ہے، بغیر کسی upstream کال کے، اس لیے رپورٹ کردہ X-OmniRoute-Response-Latency تقریباً صفر ہوتا ہے (اصل upstream تاخیر سے قطع نظر)۔ تاخیر کے لیے حساس کلائنٹس (بینچ مارکنگ، p50/p99 مانیٹرنگ) کو X-OmniRoute-Cache-Latency جوابی ہیڈر چیک کرنا چاہیے:

Value Meaning
synthetic جواب کیش سے فراہم کیا گیا؛ تاخیر حقیقی upstream وقت نہیں ہے
(absent) جواب حقیقی upstream کال سے آیا ہے

فی کلید کیش بائی پاس

API keys cacheDefaultMode کے ذریعے سیمینٹک کیش ریڈز سے آپٹ آؤٹ کر سکتی ہیں:

Value Behavior
legacy معمول کا کیش رویہ (پہلے سے طے شدہ)
bypass کیش تلاش کو مکمل طور پر چھوڑیں؛ ہمیشہ upstream کو کال کریں

کلید بناتے وقت (POST /api/keys) یا اپ ڈیٹ کرتے وقت (PATCH /api/keys/[id]) سیٹ کریں:

{ "cacheDefaultMode": "bypass" }

فی درخواست بائی پاس

کلید کی ترتیبات سے قطع نظر، کوئی بھی درخواست کیش کو بائی پاس کر سکتی ہے:

X-OmniRoute-No-Cache: true

CLIProxyAPI مینجمنٹ مطابقت

OmniRoute ان تین CLIProxyAPI مینجمنٹ اینڈ پوائنٹس کا جواب دیتا ہے جنہیں استعمال کے ڈیش بورڈز Claude اور Codex کی سبسکرپشن حدود پڑھنے کے لیے کال کرتے ہیں (مثلاً T3 Code کا cliproxy استعمال-حد ماخذ)۔ کلائنٹ کا base URL OmniRoute پر سیٹ کریں اور manage scope والی API key کو اپنی مینجمنٹ key کے طور پر استعمال کریں۔ راستے /v0/management/* اور /api/v0/management/* پر فراہم کیے جاتے ہیں۔

Method Path Description
GET /v0/management/auth-files Claude اور Codex کے OAuth کنکشنز بطور { files: [{ id, auth_index, provider, email, disabled, id_token }] }۔ کوئی ٹوکن نہیں
POST /v0/management/api-call باڈی { auth_index, method, url, header?, data? }۔ اکاؤنٹ کے ٹوکن کے ساتھ ایک allowlisted درخواست بھیجتا ہے اور { status_code, body } واپس کرتا ہے
POST /v0/management/reset-quota باڈی { auth_index }۔ ایک اکاؤنٹ کے کنکشن کول ڈاؤن، ماڈل لاک آؤٹس اور Codex کے فی-scope کول ڈاؤنز صاف کرتا ہے
  • auth_index OmniRoute کا کنکشن id ہے۔ provider، claude یا codex ہوتا ہے (صرف OAuth کنکشنز؛ anthropic API-key provider فہرست میں شامل نہیں ہے)۔ Codex کے لیے، id_token.chatgpt_account_id ذخیرہ شدہ workspace id ہے اور plan_type ذخیرہ شدہ plan ہے۔
  • api-call ایک عمومی proxy نہیں ہے۔ یہ صرف Claude GET https://api.anthropic.com/api/oauth/usage اور Codex GET https://chatgpt.com/backend-api/wham/usage، GET .../wham/rate-limit-reset-credits اور POST .../wham/rate-limit-reset-credits/consume قبول کرتا ہے، اور ہر ایک صرف متعلقہ provider کے اکاؤنٹ کے لیے۔ کوئی بھی دوسری چیز upstream سے رابطہ کیے بغیر 403 واپس کرتی ہے۔ کالر کا Authorization ہیڈر ($TOKEN$ placeholder سمیت) نظر انداز کیا جاتا ہے: OmniRoute کنکشن کا access token داخل کرتا ہے، قریباً ختم ہونے کی صورت میں پہلے اسے refresh کرتا ہے، اور صرف allowlisted headers (anthropic-beta؛ OpenAI-Beta، Originator، Chatgpt-Account-Id؛ Accept، Content-Type) آگے بھیجتا ہے۔ Chatgpt-Account-Id نہ ہونے کی صورت میں ذخیرہ شدہ workspace id پہلے سے طے شدہ ہوتی ہے۔ درخواستیں 15 سیکنڈ بعد timeout ہو جاتی ہیں اور کنکشن کا proxy استعمال کرتی ہیں۔
  • reset-quota terminal states (banned، expired، credits_exhausted) کو جوں کا توں چھوڑتا ہے۔ نامعلوم auth_index، 404 واپس کرتا ہے۔

Auth: ڈیش بورڈ session یا manage-scoped API key، login غیر فعال ہونے پر بھی لازمی ہے (راستے ALWAYS_PROTECTED_API_PATHS میں شامل ہیں)۔ صرف inference والی keys کو 403 ملتا ہے۔ ماخذ: src/lib/cliproxyCompat/managementApi.ts.


ڈیش بورڈ اور مینجمنٹ

انتظامی راستے (/api/* سوائے عوامی auth/login) ہیں۔** نہیں** عام انفرنس 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 ONE فراہم کنندہ کے لیے بڑی تعداد میں API کیز شامل کریں۔
/api/providers/import POST پارس شدہ CSV/JSON فائل (#6836) سے متضاد فراہم کنندہ LIST درآمد کریں۔ فی قطار جزوی ناکامی کے نتائج
/api/provider-nodes* مختلف فراہم کنندہ نوڈ کا انتظام
/api/provider-models GET/POST/PUT/PATCH/DELETE حسب ضرورت ماڈلز اور فی ماڈل اوور رائیڈز (شامل کریں، اپ ڈیٹ کریں، hide/show، حذف کریں)
/api/provider-models/validate-and-add POST مینجمنٹ کی توثیق شدہ، آپٹ ان سخت کنکشن کی توثیق اور جوہری کسٹم ماڈل رجسٹریشن؛ ماڈل کی توثیق دیکھیں

synced/imported ماڈلز کے لیے، PUT /api/provider-models provider، modelId، اور maxOutputTokenOverride قبول کرتا ہے: ایک مثبت عدد دستی آؤٹ پٹ ٹوکن ٹوکن سیٹ کرتا ہے، اور null ڈیفالٹ کو بحال کرنے کے لیے اسے صاف کرتا ہے۔ GET /api/provider-models?provider=<provider> ان اقدار کو modelOutputOverrides میں لوٹاتا ہے، بشمول حسب ضرورت ماڈل قطار کے بغیر ماڈلز۔ اوور رائڈ رن ٹائم max_output_tokens صلاحیت کا استعمال کرتا ہے اور ماڈل کی دوبارہ مطابقت پذیری سے بچ جاتا ہے۔ OpenAI-مطابقت فراہم کرنے والا صفحہ وہی edit/clear کنٹرولز پیش کرتا ہے اور واضح وژن سپورٹ کے ساتھ ماڈلز کو نشان زد کرتا ہے۔

ایک ہم آہنگ فراہم کنندہ نوڈ پر، لکھنے کے راستے (POST, PUT, PATCH, DELETE اور /api/provider-models/validate-and-add) ماڈل آئی ڈی کو بریئر اپ اسٹریم آئی ڈی کے طور پر اسٹور کرتے ہیں: ایک سابقہ فہرست سے چسپاں کی گئی آئی ڈی میں نوڈ کے اپنے سابقے کا کوئی بھی اہم اسٹیک ختم ہوجاتا ہے، اور جوابات اسٹور کی بازگشت کرتے ہیں۔ کیننیکل فراہم کنندگان کی کٹی ہوئی آئی ڈیز (مثلاً nvidia/nemotron-…) لفظی طور پر محفوظ کی جاتی ہیں۔ /v1/models کبھی بھی اسٹیک شدہ <prefix>/<prefix>/<model> id کا اخراج نہیں کرتا ہے۔

حسب ضرورت چیٹ تکمیل نوڈس واضح استدلال کے آپٹ آؤٹس کو اپ اسٹریم بیک اینڈ میں ڈھال لیتے ہیں۔ ایک کامیاب کنکشن ٹیسٹ ہر عین ماڈل ID کے لیے چیٹ ٹیمپلیٹ کنٹرولز کو خود بخود منتخب کرتا ہے جس کی /models انٹری ایک تسلیم شدہ owned_by قدر ثابت کرتی ہے: vllm، sglang، یا llamacpp۔ شفاف اوپن اے آئی سے مطابقت رکھنے والے ریپرز اصل ماڈل کے اندراج کو نیسٹڈ 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-مطابقت والا کنکشن چیٹ کی تکمیل کا باڈی بھیجتا ہے۔ جوابات کی درخواستیں اور عام فراہم کنندگان اپنی مقامی درخواست کی شکل کو برقرار رکھتے ہیں۔ عام OpenAI reasoning_effort پاس تھرو کو مجبور کرنے کے لیے reasoningControl کو openai پر سیٹ کریں، یا خودکار پتہ لگانے کے لیے it/set کو null پر چھوڑ دیں۔

Claude کوڈ آٹو موڈ درجہ بندی ڈیفالٹ مقامی سوچ کو غیر فعال کرنے کی درخواست کرتا ہے جب ان میں کوئی واضح استدلال کنٹرول نہیں ہوتا ہے۔ پتہ لگانے میں کلاسیفائر کے سسٹم مارکر کو کلاڈ فارمیٹ کی درخواستوں میں استعمال کیا جاتا ہے، نہ کہ ماڈل کے نام یا تکمیل کی حد۔ واضح باڈی کنٹرولز، تعاون یافتہ effort/thinking ہیڈرز، روٹنگ کے اصول، اور حل شدہ ماڈل کی کوششیں اپنی موجودہ ترجیح کو برقرار رکھتی ہیں۔ درجہ بندی کرنے والے دونوں مراحل اپنے اشارے، تکمیل کی حدود، سٹاپ سیکوینس، اور حقیقی اپ اسٹریم اجازت کے فیصلے کو برقرار رکھتے ہیں۔ دوسرا مرحلہ اب بھی اپنی مطلوبہ مرئی استدلال کو عام متن کے طور پر پیش کر سکتا ہے۔

OAuth بہتا ہے۔

اختتامی نقطہ طریقہ تفصیل
/api/oauth/[provider]/[action] مختلف فراہم کنندہ کے لیے مخصوص OAuth

روٹنگ اور ترتیب

اختتامی نقطہ طریقہ تفصیل
/api/models GET/PUT ماڈل کی فہرست / عرف کی تازہ کاری
/api/models/alias GET/POST ماڈل عرفی نام
/api/models/catalog GET فراہم کنندہ + قسم کے تمام ماڈلز
/api/combos* مختلف کومبو مینجمنٹ
/api/keys* مختلف API کلیدی انتظام
/api/pricing GET ماڈل کی قیمتوں کا تعین

ماڈل کی حد ثابت کرنا

GET /api/models?withLimits=1 ( true بھی؛ 0/false یا اسے چھوڑنے سے پہلے سے طے شدہ پے لوڈ میں کوئی تبدیلی نہیں ہوتی ہے) ہر ماڈل قطار میں contextWindow، maxInputTokens، maxOutputTokens اور ایک capsSource آبجیکٹ شامل کرتا ہے۔ capsSource اس اصول کا نام دیتا ہے جو ہر حد کو فراہم کرتا ہے، لہذا ایک حیران کن حد (مثال کے طور پر 1M ماڈل پر 128k) اس کی اصل کا پتہ لگایا جا سکتا ہے۔ حل شدہ اقدار وہی ہیں جو روٹنگ استعمال کرتی ہیں۔ جھنڈا صرف فیلڈز کو جوڑتا ہے اور کبھی کسی قدر کو تبدیل نہیں کرتا ہے۔ کوئی دوسری withLimits قدر 400 کے ساتھ مسترد کر دی جاتی ہے۔

capsSource قدر اصل
override:context مستقل سیاق و سباق-ونڈو اوور رائڈ (model_context_overrides)
override:max_input / override:max_output برقرار max_input_tokens / max_output_tokens صلاحیت کو اوور رائڈ
static-authoritative:<provider>/<model> جامد مستند سیاق و سباق-ونڈو ٹیبل
synced:<provider>/<model> models.dev کی مطابقت پذیری والی قطار
registry:<provider>/<model> فراہم کنندہ کی رجسٹری کا اندراج
spec:<model> جامد ماڈل کی تفصیلات
effort-base: سابقہ کوشش کے لاحقہ متغیر کے بیس ماڈل سے لی گئی قطار
none کوئی ذریعہ حد کا اعلان نہیں کرتا (قدر ہے null)

نفاذ: src/lib/modelCapabilities.ts میں getResolvedModelCapabilitiesWithLimitSources() اور src/lib/modelCapabilityLimits.ts میں ترجیحی سلسلہ۔

استعمال اور تجزیات

اختتامی نقطہ طریقہ تفصیل
/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 رولنگ per-provider/model لیٹنسی ایگریگیٹ (avg/p50/p95/p99, کامیابی کی شرح)؛ فلٹرز: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health GET call_logs — write/read تناسب، p50/p90/p99 تحریری سائز کی تقسیم، بھاری تحریری ارتکاز، فی ماڈل کی تقسیم، اور healthy/degraded/thrash/no-data فیصلے پر فوری کیش صحت کا خلاصہ؛ query params range (1h| 24h| 7d| 30d, ڈیفالٹ 24h) اور اختیاری model (#8827)

API کلیدی اجازتیں۔

PATCH /api/keys/{id} موجودہ کلید کی اجازتوں کو اپ ڈیٹ کرتا ہے۔ ہر /api/keys* روٹ کی طرح اس کو بھی انتظامی اجازت کی ضرورت ہوتی ہے (دیکھیں Management Authentication )، کسی inference key کی نہیں۔ صرف وہ فیلڈز بھیجیں جنہیں آپ تبدیل کرنا چاہتے ہیں۔ ان میں سے کسی کے ساتھ درخواست No valid fields to update کے ساتھ مسترد نہیں کی جاتی ہے۔ قبول شدہ فیلڈز کی تعریف src/shared/validation/schemas/keys.ts میں updateKeyPermissionsSchema کے ذریعے کی گئی ہے۔

میدان قسم نوٹس
name سٹرنگ، 1-200 حروف
isActive بولین
isBanned بولین
expiresAt ISO 8601 datetime یا null null ایکسپائری کو صاف کرتا ہے۔
modelAccessMode all | restricted جب موڈ all ہو تو allowedModels خالی ہونا چاہیے۔
allowedModels, blockedModels تاروں کی صف، 1000 تک
allowedCombos تاروں کی صف، 500 تک وہ دروازے جو کلید کو جوڑتے ہیں کال کر سکتے ہیں۔ براہ راست ماڈلز modelAccessMode / allowedModels کے زیر انتظام ہیں۔
connectionAccessMode all | restricted allowedConnections غیر خالی ہونا ضروری ہے جب restricted اور خالی ہو جب all
allowedConnections UUIDs کی صف، 100 تک
allowAutoCombos بولین false اس کلید کے ساتھ auto/* ماڈلز کی درخواستوں کو مسترد کرتا ہے۔ وہ چابیاں جو اسے کبھی سیٹ نہیں کرتی ہیں اس کی اجازت ہے۔
catalogScope all | combos | models اس کلید کے لیے GET /v1/models کیا فہرست رکھتا ہے (صرف کومبوز، صرف ماڈلز، یا دونوں)؛ یہ تبدیل نہیں کرتا کہ کلید کیا کال کر سکتی ہے۔
forcedModel 300 حروف تک کی تار، یا null اس model/combo کو روٹس چیٹ کی درخواستیں , 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 بولین
allowUsageCommand بولین
usageLimitEnabled بولین
dailyUsageLimitUsd, weeklyUsageLimitUsd نمبر >= 0 یا null
fiveHourUsageLimitUsd نمبر >= 0 یا null 5 گھنٹے کا USD بجٹ رولنگ، روزانہ اور ہفتہ وار حدود (usageLimitEnabled, UNPRICED_USAGE_BUDGET_POLICY) کی طرح نافذ۔ retry-after وہ وقت ہوتا ہے جب ونڈو میں سب سے پرانا خرچ ختم ہو جاتا ہے، جو ایک کلید کو اپنی حد سے کہیں زیادہ روک سکتا ہے۔
chaosModeEnabled بولین
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 allowlist/blocklist
/api/settings/thinking-budget GET/PUT Thinking/reasoning** درخواست** دوبارہ لکھنے کا موڈ (پاس تھرو / آٹو پٹی / کسٹم / انکولی)۔ کمپریشن سے آزاد۔ دیکھیں THINKING_BUDGET.
/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 کیو مین رول میٹا ڈیٹا کی فہرست بنائیں
/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 preview/test چلائیں۔
/api/context/rtk/raw-output/[id] GET پوائنٹر آئی ڈی کے ذریعہ برقرار رکھی ہوئی ترمیم شدہ خام آؤٹ پٹ پڑھیں
/api/context/combos GET/POST کمپریشن کومبو list/create
/api/context/combos/[id] GET/PUT/DELETE کمپریشن کومبو detail/update/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: probe-cache scalers، failedConnections when failed>0، اور staleDbNonOkCount (SQLite چپچپا test_status، گیج نہیں)۔ دیکھیں MONITORING_GUIDE.
/api/cache/stats GET/DELETE کیشے کے اعدادوشمار / صاف
/api/modality-bridge/stats GET ان-میموری attempts، کامیابیاں/bridged، ناکامیاں، کیش ہٹس، totalLatencyMs، latencySamples، نمونہ نما averageLatencyMs، اور آخری استعمال کا وقت (دوبارہ شروع ہونے پر دوبارہ ترتیب دینا؛ انتظامی توثیق)
/api/modality-bridge/video/runtime GET مینجمنٹ auth/probe سے پہلے سخت بھروسہ مند-لوپ بیک چیک کریں؛ سینیٹائزڈ FFmpeg/ffprobe کی دستیابی اور ورژن (نو اسٹور)
/api/modality-bridge/video/extract POST اندرونی تصدیق شدہ ٹرسٹڈ لوپ بیک بائٹ بروکر؛ 50 MiB ان پٹ، پابند queue/32 MiB آؤٹ پٹ، 503 صلاحیت، 499 منقطع، 504 آخری تاریخ؛ عوامی اپ لوڈ API نہیں ہے۔

ویڈیو فریم ڈرل ڈاؤن

GET /api/v1/video-bridge/drilldown واضح طور پر رضامندی والی ویڈیو برج کی درخواست کے بعد x-omniroute-video-drilldown میں واپس کیے گئے کرایہ دار کے پابند مبہم ہینڈل کو پڑھتا ہے۔ ریڈز اور DELETE دونوں کو ہمیشہ ایک درست API کلید اور آپریٹر کی آزاد modalityBridgeVideoDrilldownRemoteEnabled اجازت کی ضرورت ہوتی ہے۔ پیداوار برقرار رکھنے کے لیے اضافی طور پر modalityBridgeVideoDrilldownEnabled اور سخت فی پارٹ drilldown: true کی ضرورت ہوتی ہے۔ اگر کلید کے پاس بغیر کسی اختتامی نقطہ کی اجازت کی فہرست ہے، تو اس میں GET اور DELETE دونوں کے لیے video شامل ہونا چاہیے، چاہے کال کرنے والا /v1 استعمال کرے یا /api/v1۔

GET استفسار: مطلوبہ handle; اختیاری variant (preview, standard, detail) , limit (1–8؛ میراثی frames قبول کیا جاتا ہے لیکن اسے limit کے ساتھ جوڑا نہیں جا سکتا)، صفر پر مبنی page، اور start/end سیکنڈز۔ جب دونوں فوکس باؤنڈز فراہم کیے جاتے ہیں، end start سے بڑا ہونا چاہیے۔ Duplicate/unknown استفسار کی چابیاں مسترد کر دی گئی ہیں۔ کامیاب جوابات میں derivation, durationSeconds, frames, hasMore, page, variant, اور اختیاری focusWindow; No-store JSON حد 32 MiB پر ہے بشمول Base64۔ بڑے پیمانے پر آؤٹ پٹ 413 ریٹرن۔ کم فریموں کی درخواست کریں۔

DELETE /api/v1/video-bridge/drilldown?handle=... { "removed": 0|1 } لوٹاتا ہے۔ نامعلوم، ایکسپائرڈ اور کراس کلید GETs ناقابل شناخت 404 جوابات ہیں۔ cross-key DELETE مالک کے اندراج کو نہیں ہٹا سکتا۔ غیر فعال رسائی کی واپسی 403، missing/invalid توثیق 401، غلط سوالات 400، منسوخی 499 اور عارضی غلطیاں 503۔ ہینڈلز مقامی پروسیس ہیں، دس منٹ کے بعد ختم ہو جاتے ہیں، اور دوبارہ شروع ہونے سے بچ نہیں پاتے۔ نئے ہینڈلز v1. کے علاوہ 32 بائٹ رینڈم Base64URL ٹوکن استعمال کرتے ہیں۔ صرف ٹوکن ہیشز برقرار ہیں۔ لیگیسی 64-ہیکس ٹوکن مطابقت کے لیے مصنوعی طور پر پڑھنے کے قابل رہتے ہیں۔ رضامندی، کوٹہ اور مختلف اخذ کی تفصیلات کے لیے ویڈیو برج گارڈریلز دیکھیں۔

بیک اپ اور Export/Import

اختتامی نقطہ طریقہ تفصیل
/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 (بذریعہ 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/* مختلف کلاؤڈ مینجمنٹ

سرنگیں۔

اختتامی نقطہ طریقہ تفصیل
/api/tunnels/cloudflared GET ڈیش بورڈ کے لیے Cloudflare Quick Tunnel install/runtime اسٹیٹس پڑھیں
/api/tunnels/cloudflared POST Cloudflare کوئیک ٹنل کو فعال یا غیر فعال کریں (action=enable/disable)
/api/tunnels/ngrok GET ڈیش بورڈ کے لیے ngrok ٹنل رن ٹائم اسٹیٹس پڑھیں
/api/tunnels/ngrok POST ngrok ٹنل کو فعال یا غیر فعال کریں (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 query param کے ذریعے کسٹم ایجنٹ کو ہٹا دیں۔

GET جواب میں agents[] (id، نام، بائنری، ورژن، انسٹال، پروٹوکول، isCustom) اور summary (کل، انسٹال، notFound، builtIn، کسٹم) شامل ہیں۔

لچک اور شرح کی حدود

اختتامی نقطہ طریقہ تفصیل
/api/resilience GET/PATCH Get/update درخواست کی قطار، کنکشن کولڈاؤن، فراہم کنندہ بریکر، اور انتظار کی ترتیبات
/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 واضح تحفظ کو غیر فعال کر دیتا ہے لیکن عالمی آٹو-انبل سیفٹی نیٹ (autoEnableApiKeyProviders) سے باہر ایک فعال API-key کنکشن کا انتخاب نہیں کرتا ہے۔
/api/rate-limit GET عالمی شرح کی حد کی ترتیب (فرسودہ؛ عرف سے /api/rate-limits)

/api/resilience/* چاروں راستوں کی ضرورت ہے۔** انتظامیہ کی تصدیق** (requireManagementAuth) فراہم کنندہ بریکر بمقابلہ کنکشن کولڈاؤن بمقابلہ ماڈل لاک آؤٹ کی مکمل خرابی کے لیے لچک (توسیع شدہ) دیکھیں۔

ایولز

اختتامی نقطہ طریقہ تفصیل
/api/evals GET/POST ایول سویٹس کی فہرست بنائیں / تشخیص چلائیں۔

پالیسیاں

اختتامی نقطہ طریقہ تفصیل
/api/policies GET/POST/DELETE روٹنگ کی پالیسیوں کا نظم کریں۔

تعمیل

اختتامی نقطہ طریقہ تفصیل
/api/compliance/audit-log GET تعمیل آڈٹ لاگ (آخری N)

v1beta (جیمنی سے ہم آہنگ)

اختتامی نقطہ طریقہ تفصیل
/v1beta/models GET Gemini فارمیٹ میں ماڈلز کی فہرست بنائیں
/v1beta/models/{...path} POST Gemini generateContent اختتامی نقطہ

یہ اختتامی نقطے Gemini کے API فارمیٹ کو ان کلائنٹس کے لیے آئینہ دیتے ہیں جو مقامی Gemini SDK مطابقت کی توقع رکھتے ہیں۔

اندرونی / سسٹم APIs

اختتامی نقطہ طریقہ تفصیل
/api/init GET پس منظر کی مطابقت پذیری کی خدمات شروع کریں (انتظام کی توثیق)
/api/tags GET اولاما کے موافق ماڈل ٹیگز ( Ollama کلائنٹس کے لیے)
/api/restart POST ٹرگر مکرم سرور دوبارہ شروع
/api/shutdown POST مکرم سرور شٹ ڈاؤن کو متحرک کریں۔
/api/system/env/repair POST OAuth فراہم کنندہ کے ماحولیاتی متغیرات کی مرمت کریں۔
/api/system/version GET Current/latest ورژن، اپ ڈیٹ اسٹیٹس، ریلیز چینل
/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

صرف لوپ بیک مینجمنٹ روٹ (ایڈمن اوتھ)۔ چل رہا ورژن، تازہ ترین شائع شدہ ورژن اور خودکار اپ ڈیٹ کی حیثیت لوٹاتا ہے۔ 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 چینل: -nightly.* ورژنز کے لیے nightly ، دیگر پری ریلیزز کے لیے next (-rc.*, -beta.*, -alpha.*)، lts channels.latest سے پرانے میجر کے مستحکم ورژن کے لیے، بصورت دیگر latest۔ scripts/release/dist-tag.mjs جیسے ہی اصول، جو اشاعت کے وقت npm ڈسٹ ٹیگ کو چنتا ہے۔
  • channels — npm view omniroute dist-tags (رجسٹری HTTP فال بیک) سے ہر ڈسٹ ٹیگ کا ہیڈ شائع کیا، اسی 10 منٹ کے TTL کے ساتھ latest کے ساتھ کیش کیا گیا۔ latest ہمیشہ موجود ہوتا ہے ( latest فیلڈ میں واپس آتا ہے، پھر "unavailable")؛ next، nightly اور lts صرف اس وقت ظاہر ہوتے ہیں جب وہ ڈسٹ ٹیگ موجود ہو۔ Cache-Control: no-cache درخواست دونوں تلاش کو تازہ کرتی ہے۔

چینل ماڈل (latest = v3 جب تک 4.0 GA، next = rc، nightly = develop بناتا ہے، 4.0 GA کے بعد lts = v3 پیچ) 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 "file=@recording.mp3" \
  -F "model=openai/whisper-1"

جواب:

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

مثالی ماڈل IDs: openai/whisper-1 (OpenAI کلید درکار ہے)، openrouter/deepgram/nova-3 (OpenRouter کلید درکار ہے)، deepgram/nova-3 (مقامی Deepgram کلید درکار ہے)۔ سادہ deepgram/nova-3 درخواست OpenRouter استعمال نہیں کرتی۔

معاونت یافتہ فارمیٹس: mp3، wav، m4a، flac، ogg، webm۔

Gemini Live (gemini/gemini-3.5-transcribe-live): Gemini Live WebSocket کے ذریعے فائل موڈ ٹرانسکرپشن (Gemini API کلید درکار ہے)۔ اپ لوڈ کو ffmpeg کے ذریعے 16 kHz مونو PCM میں تبدیل کیا جاتا ہے (PATH پر موجود ہونا ضروری ہے، سوائے اس صورت کے جب فائل پہلے ہی 16 kHz مونو PCM WAV ہو)، سیشن میں اسٹریم کیا جاتا ہے اور حتمی متن { "text": "..." } کے طور پر واپس کیا جاتا ہے۔ اختیاری language اور prompt فارم فیلڈز آگے بھیجے جاتے ہیں۔ حدود: 25 MiB سے بڑی اپ لوڈز یا 10 منٹ سے زیادہ طویل ڈی کوڈ شدہ آڈیو 413 کا جواب حاصل کرتے ہیں؛ 60 سیکنڈ سے زیادہ چلنے والی تبدیلی کا عمل ختم کر دیا جاتا ہے اور 504 کا جواب دیا جاتا ہے۔ API کلید صرف x-goog-api-key ہیڈر میں بھیجی جاتی ہے، WebSocket URL میں کبھی نہیں۔


Ollama مطابقت

ایسے کلائنٹس کے لیے جو Ollama کا API فارمیٹ استعمال کرتے ہیں:

# چیٹ اینڈ پوائنٹ (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":"hello"}]}'

نوٹس:

  • ٹوکن والے عرف /v1/* اور /api/tags جیسے ہی ہینڈلرز دوبارہ استعمال کرتے ہیں؛ جوابی ساختیں یکساں رہتی ہیں۔
  • جب بھی کلائنٹ حسبِ ضرورت ہیڈرز کو سپورٹ کرے، Authorization: Bearer ... کو ترجیح دیں۔
  • URL پر مبنی ٹوکنز 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
}

# id کے ذریعے ٹوکن کی حد حذف کریں
DELETE /api/usage/token-limits?id=tl-abc

اسکیما نوٹس (setTokenLimitSchema): apiKeyId اور scopeType (model | provider | global) درکار ہیں۔ scopeType اگر global نہ ہو تو scopeValue درکار ہے (مثلاً model اسکوپ کے لیے ماڈل id، اور provider اسکوپ کے لیے provider id)۔ tokenLimit ایک مثبت عدد صحیح ہونا چاہیے (اسٹرنگ سے تبدیل کیا جاتا ہے)۔ اختیاری: id (بنانے کے لیے چھوڑ دیں، اپ ڈیٹ کرنے کے لیے فراہم کریں)، resetInterval (daily | weekly | monthly، ڈیفالٹ monthly)، resetTime (HH:MM)، enabled (ڈیفالٹ true)۔ GET کے جوابات ہر حد میں tokensUsed، remaining، windowStart، periodStartAt، اور nextResetAt شامل کرتے ہیں۔ یہ مینجمنٹ-کلاس اینڈپوائنٹ ہے (توثیق مرکزی authz پائپ لائن کے ذریعے نافذ کی جاتی ہے)۔

درخواست کی پراسیسنگ

  1. کلائنٹ /v1/* کو درخواست بھیجتا ہے
  2. روٹ ہینڈلر handleChat، handleEmbedding، handleAudioTranscription، یا handleImageGeneration کو کال کرتا ہے
  3. ماڈل حل کیا جاتا ہے (براہِ راست provider/model یا alias/combo)
  4. اکاؤنٹ کی دستیابی کی فلٹرنگ کے ساتھ مقامی DB سے اسناد منتخب کی جاتی ہیں
  5. چیٹ کے لیے: handleChatCore semantic/signature کیش چیک کرتا ہے اور combo کی کمپریشن ترتیبات حل کرتا ہے
  6. فعال ہونے کی صورت میں provider translation سے پہلے پیشگی کمپریشن چلتی ہے (lite، Caveman، RTK، یا stacked)
  7. provider executor upstream درخواست بھیجتا ہے
  8. جواب کو کلائنٹ کے فارمیٹ میں واپس تبدیل کیا جاتا ہے (چیٹ)، یا جوں کا توں واپس کیا جاتا ہے (embeddings/images/audio)
  9. استعمال، کمپریشن کے تجزیات، اور درخواست کے لاگز ریکارڈ کیے جاتے ہیں
  10. combo کے قواعد کے مطابق خرابیوں کی صورت میں fallback لاگو ہوتا ہے

مکمل آرکیٹیکچر حوالہ: ARCHITECTURE.md


کومبو مینجمنٹ

اعلیٰ سطح کے روٹنگ کومبو (جن کا خلاصہ پہلے ہی /api/combos* کے تحت دیا جا چکا ہے) کو ماڈل id پیٹرن سے 1:1 بھی میپ کیا جا سکتا ہے، جس سے OpenAI طرز کے ماڈل id کو کسی کومبو کی طرف شفاف طور پر ری ڈائریکٹ کرنا ممکن ہوتا ہے۔

Method Path Description
GET /api/model-combo-mappings تمام model→combo میپنگز کی فہرست
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)۔


ویب ہُکس

OmniRoute ایونٹس (درخواست کی تکمیل، کوٹے کا ختم ہونا، کلید کی گردش وغیرہ) کے لیے آؤٹ باؤنڈ ویب ہُک سبسکرپشنز۔

طریقہ پاتھ وضاحت
GET /api/webhooks ویب ہُکس کی فہرست (راز <prefix>... کی صورت میں مخفی کیے جاتے ہیں)
POST /api/webhooks ویب ہُک بنائیں — باڈی: {url, events?: ["*"], secret?, description?}
GET /api/webhooks/[id] ویب ہُک حاصل کریں
PUT /api/webhooks/[id] url/events/secret/description کو اپ ڈیٹ کریں
DELETE /api/webhooks/[id] ویب ہُک ہٹائیں
POST /api/webhooks/[id]/test ویب ہُک URL پر ٹیسٹ پے لوڈ بھیجیں اور ترسیل کی حیثیت واپس کریں

تصدیق: مینجمنٹ سیشن/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 ٹوکن، یا manage/admin اسکوپ والی API کلید؛ صرف inference والی API کیز کو 403 ملتا ہے۔ /v1/quotas/check اور /v1/issues/report بھی دیکھیں۔


ایجنٹس پروٹوکول

Cloud agent tasks (Claude Code, Codex Cloud, OpenHands وغیرہ) جو OmniRoute صارفین کی جانب سے ریموٹ طور پر انجام دیے جاتے ہیں۔

Method Path Description
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 سیٹ ہو تو اپ اسٹریم cloud agent سے اسٹیٹس کو ہم وقتی طور پر تازہ کرتا ہے
POST /api/v1/agents/tasks/[id] امتیازی ایکشن: {action: "approve"}, {action: "message", message}, یا {action: "cancel"}
DELETE /api/v1/agents/tasks/[id] id کے ذریعے مخصوص ٹاسک حذف کریں

Auth: ہر method کے لیے management auth درکار ہے (requireCloudAgentManagementAuth)۔ v3.8.0 سے پہلے یہ غیر مصدقہ تھے — اہم تبدیلی کے لیے commit 588a0333 دیکھیں۔

# Claude Code cloud task بنائیں
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":"..."}}'

مینجمنٹ پراکسیز

آؤٹ باؤنڈ HTTP(S)/SOCKS پراکسیز جنہیں providers، accounts یا عالمی سطح پر تفویض کیا جا سکتا ہے۔

Method Path Description
GET /api/v1/management/proxies پراکسیز کی فہرست (اگر ?id= دیا جائے تو ایک پراکسی واپس کرتا ہے؛ ?id=&where_used=1 کے ساتھ assignment graph واپس کرتا ہے)
POST /api/v1/management/proxies پراکسی بنائیں — باڈی کی توثیق createProxyRegistrySchema سے ہوتی ہے
PATCH /api/v1/management/proxies پراکسی اپ ڈیٹ کریں — باڈی کی توثیق updateProxyRegistrySchema سے ہوتی ہے (id درکار ہے)
DELETE /api/v1/management/proxies?id=...&force=1 پراکسی حذف کریں (force=1 استعمال کرنے سے assignments الگ ہو جاتے ہیں)
GET /api/v1/management/proxies/assignments assignments کی فہرست — proxy_id, scope, scope_id کے ذریعے فلٹر کیا جا سکتا ہے؛ کسی connection کے لیے فعال پراکسی حل کرنے کی خاطر resolve_connection_id=<id> پاس کریں
PUT /api/v1/management/proxies/assignments تفویض کریں — باڈی کی توثیق proxyAssignmentSchema ({scope, scopeId?, proxyId?}) سے ہوتی ہے۔ dispatcher cache صاف کرتا ہے
PUT /api/v1/management/proxies/bulk-assign بلک تفویض — باڈی کی توثیق bulkProxyAssignmentSchema ({scope, scopeIds[], proxyId?}) سے ہوتی ہے
GET /api/v1/management/proxies/health?hours=24 مقررہ مدت کے دوران مجموعی پراکسی صحت (کامیابی/ناکامی کی تعداد، latency)

Auth: ہر route پر management session/API key درکار ہے (requireManagementAuth)۔

ٹاسک کی تفصیل میں موجود POST /api/v1/management/proxies/[id]/assignments اور POST /api/v1/management/proxies/[id]/health اوپر دکھائے گئے flat /assignments اور /health routes کے ذریعے فراہم کیے جاتے ہیں — codebase میں فی-id subroutes موجود نہیں ہیں۔


لچک (توسیع شدہ)

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 کو سپورٹ کرتا ہے؛ یہی فیلڈز Dashboard → Settings → Resilience میں بھی دستیاب ہیں۔

# ایک ماڈل کا لاک آؤٹ صاف کریں
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 → "Resilience Runtime State" اور docs/architecture/RESILIENCE_GUIDE.md دیکھیں۔

ریٹ-لمٹ قطار اور خودکار فعال کاری کا حفاظتی نظام

  • مجاز تحریری راستہ: POST /api/rate-limits، جس کی باڈی {"connectionId": "<id>", "enabled": true|false} ہے، کسی کنکشن کے لیے ریٹ-لمٹ تحفظ کو ٹوگل کرنے کا مجاز انتظامی اینڈپوائنٹ ہے۔ PUT /api/providers/[id] جان بوجھ کر rateLimitProtection میں ترمیم یا اسے تبدیل نہیں کرتا (#11278)۔
  • enabled: false کے معانی: enabled: false سیٹ کرنے سے کنکشن کے لیے واضح تحفظ ختم ہو جاتا ہے، لیکن یہ فعال API-key کنکشن کو عالمی خودکار فعال کاری کے حفاظتی نظام (autoEnableApiKeyProviders = true) سے خارج نہیں کرتا۔ reconcileEnabledConnections (open-sse/services/rateLimitManager.ts) میں false اور undefined یکساں ہیں؛ واضح تحفظ کے بغیر فعال API-key کنکشن خودکار فعال کاری کے حفاظتی نظام کے تحت محفوظ رہتے ہیں۔
  • عالمی غیر فعال کاری: API-key کنکشنز کو ریٹ-لمٹ قطاروں کے بغیر چلانے کے لیے، حفاظتی نظام کو عالمی سطح پر RATE_LIMIT_AUTO_ENABLE=false (env) کے ذریعے یا resilienceSettings.requestQueue.autoEnableApiKeyProviders = false (Settings → Resilience / 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 کلید۔ مارکیٹ پلیس کی تلاش کے راستے انتظامی تصدیق یا Bearer API کلید (isAuthenticated) میں سے کسی ایک کو قبول کرتے ہیں۔


میموری

مستقل گفتگوئی/حقیقتی میموری اسٹور، جو فی API key / سیشن کے دائرہ کار میں محدود ہے۔

طریقہ راستہ تفصیل
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 میموری ذیلی نظام کی صحت (DB کنیکٹیویٹی، ایمبیڈنگز بیک اینڈ، ویکٹر انڈیکس کی حالت)

توثیق: مینجمنٹ سیشن/API key (requireManagementAuth)۔ type enum: FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (src/lib/memory/types.ts میں MemoryType دیکھیں)۔


MCP سرور

OmniRoute میں 3 ٹرانسپورٹس (stdio، SSE، streamable-http) اور محدود دائرہ کار والے ٹولز کے ساتھ سرایت شدہ Model Context Protocol سرور شامل ہے۔ ذیل کے ڈیش بورڈ اینڈ پوائنٹس اسٹیٹس/آڈٹ ڈیٹا پڑھتے ہیں اور HTTP ٹرانسپورٹس کے لیے پراکسی کا کام کرتے ہیں۔

طریقہ راستہ تفصیل --------------------
GET /api/mcp/status ہارٹ بیٹ، ٹرانسپورٹ، آن لائن حالت، آخری کال، نمایاں ٹولز، 24 گھنٹوں کی کامیابی کی شرح
GET /api/mcp/tools MCP ٹولز کی فہرست، جن میں name, description, scopes, phase, auditLevel, sourceEndpoints شامل ہیں
GET /api/mcp/sse SSE ٹرانسپورٹ کے لیے SSE اسٹریم کھولیں (اگر MCP غیر فعال ہو یا ٹرانسپورٹ میں عدم مطابقت ہو تو 503 واپس کرتا ہے)
POST /api/mcp/sse SSE ٹرانسپورٹ پر JSON-RPC فریم بھیجیں
GET /api/mcp/stream Streamable HTTP ٹرانسپورٹ کا SSE پہلو کھولیں (سرور کی جانب سے شروع کیے گئے پیغامات)
POST /api/mcp/stream Streamable HTTP ٹرانسپورٹ پر JSON-RPC فریم بھیجیں
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 سے مخصوص توثیقی سطح (Bearer API key جس میں mcp scope ہو) کی پابندی کرتی ہیں؛ status/tools/audit* روٹس ڈیش بورڈ سے قابلِ مطالعہ ہیں (ڈیش بورڈ ہوسٹ تک رسائی کے علاوہ اضافی توثیق درکار نہیں)۔

دونوں HTTP ٹرانسپورٹس settings.mcpEnabled اور settings.mcpTransport کے ذریعے محدود ہیں — ٹرانسپورٹ میں عدم مطابقت 400 واپس کرتی ہے، جبکہ MCP کی غیر فعال حالت 503 واپس کرتی ہے۔


A2A سرور

OmniRoute ایک A2A (Agent-to-Agent) 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 ہم وقت skill کا اجرا؛ {task, artifacts, metadata} واپس کرتا ہے
message/stream اسی skill سیٹ کا اسٹریمنگ SSE اجرا
tasks/get taskId کے ذریعے task حاصل کریں
tasks/cancel taskId کے ذریعے task منسوخ کریں

بلٹ اِن skills: smart-routing، quota-management، provider-discovery، cost-analysis، health-report۔

ایجنٹ کارڈ

GET /.well-known/agent.json

عوامی A2A ایجنٹ کارڈ (نام، وضاحت، صلاحیتیں، skill catalog، auth scheme) واپس کرتا ہے — 1h کے لیے عوامی طور پر کیش کیا جاتا ہے۔ auth درکار نہیں۔

REST مددگار

طریقہ راستہ وضاحت
GET /api/a2a/status A2A کی فعالیت + task کے اعدادوشمار + کیش شدہ ایجنٹ کارڈ کا خلاصہ
GET /api/a2a/tasks 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] ایک task حاصل کریں
POST /api/a2a/tasks/[id]/cancel ایک task منسوخ کریں

توثیق: REST مددگار management auth کے بغیر چلتے ہیں (ڈیش بورڈ سے پڑھے جا سکتے ہیں)؛ JSON-RPC /a2a راستہ، اگر تشکیل دیا گیا ہو، تو Bearer OMNIROUTE_API_KEY استعمال کرتا ہے۔


کلاؤڈ، Evals اور Assess

طریقہ راستہ وضاحت
POST /api/cloud/auth Bearer key کی تصدیق کریں اور cloud sync clients کے لیے masked provider connections + model aliases واپس کریں
POST /api/cloud/credentials/update cloud-synced provider کے لیے encrypted credentials اپ ڈیٹ کریں
POST /api/cloud/model/resolve مقامی routing table استعمال کرتے ہوئے logical model id کو concrete provider/model میں resolve کریں
GET /api/cloud/models/alias cloud sync کے لیے ظاہر کیے گئے model aliases کی فہرست
GET /api/assess تازہ ترین assessment categorizations پڑھیں (per-provider/model)
POST /api/assess assessment چلائیں — body: `{scope: {type:"all"} {type:"provider", providerId} {type:"model", modelId}, trigger?}`
GET /api/evals بلٹ اِن eval suites + حالیہ ترین runs کی فہرست
POST /api/evals eval run شروع کریں
POST /api/evals/suites custom eval suite بنائیں — body کی توثیق evalSuiteSaveSchema کے ذریعے ہوتی ہے
GET /api/evals/suites/[id] custom eval suite حاصل کریں

توثیق: /api/cloud/auth براہِ راست Bearer key کی توثیق کرتا ہے اور ہر connection کی masked key اور projectId صرف ایسی key کے لیے واپس کرتا ہے جس کے پاس manage / admin scope ہو؛ دیگر /api/cloud/*، /api/evals/*، اور /api/assess راستوں کے لیے management session/API key درکار ہوتی ہے۔ /api/assess POST، discriminated-union scope schema کے ساتھ 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
}

توثیق: مینجمنٹ سیشن (ڈیش بورڈ کی 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 ٹولز کا انتظام

OmniRoute کے ساتھ مربوط CLI ٹولز کا انتظام کریں (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 ایک پرانی Codex YAML کی نشاندہی کرتا ہے)
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 Antigravity MITM پراکسی کی حالت (یعنی "antigravity-mitm" CLI ٹول)
POST /api/cli-tools/antigravity-mitm/alias antigravity-mitm عرفیات کنفیگر کریں

تصدیق: مینجمنٹ سیشن درکار ہے۔


ایجنٹ اسکلز

AI ایجنٹ اسکلز کا انتظام کریں (ایجنٹس کے لیے OpenAI کے کسٹم GPTs سے ملتی جلتی سہولت)۔

طریقہ پاتھ وضاحت
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 کلید درکار ہے۔


کیش کا انتظام

سیمنٹک کیش اور ریزننگ کیش کا انتظام کریں۔

Method Path Description
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> یا کوئی پیرامیٹر نہیں (سب)

Auth: مینجمنٹ سیشن درکار ہے۔


میموری سسٹم

مستقل میموری کا انتظام کریں (FTS5 + ویکٹر ایمبیڈنگز)۔

Method Path Description
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 + ویکٹر) — اعدادوشمار اسی رسپانس میں شامل ہیں

Auth: مینجمنٹ سیشن یا مینجمنٹ اسکوپ والی API key درکار ہے۔


Webhooks

ایونٹس کے لیے ویب ہک سبسکرپشنز کا انتظام کریں۔

Method Path Description
GET /api/webhooks تمام ویب ہک سبسکرپشنز کی فہرست
POST /api/webhooks ویب ہک سبسکرپشن بنائیں — باڈی: {url, events[], secret?, active?}
GET /api/webhooks/[id] مخصوص ویب ہک سبسکرپشن حاصل کریں
PUT /api/webhooks/[id] ویب ہک سبسکرپشن اپ ڈیٹ کریں
DELETE /api/webhooks/[id] ویب ہک سبسکرپشن حذف کریں
GET /api/webhooks/[id]/deliveries ویب ہک کے لیے ترسیل کی تاریخ کی فہرست (کامیابی/ناکامی کا لاگ)
POST /api/webhooks/[id]/test ویب ہک کو ٹیسٹ ایونٹ بھیجیں

Auth: مینجمنٹ سیشن درکار ہے۔

مکمل ایونٹ اقسام کے لیے Webhooks Framework دیکھیں۔


مہارتوں کا فریم ورک

مہارتوں (ایجنٹک ایکسٹینشنز فریم ورک) کا نظم کریں۔

Method Path Description
GET /api/skills تمام انسٹال شدہ مہارتوں کی فہرست (بلٹ اِن + حسبِ ضرورت)
POST /api/skills/install مقامی پاتھ یا URL سے مہارت انسٹال کریں
DELETE /api/skills/[id] مہارت اَن انسٹال کریں
PUT /api/skills/[id] مہارت فعال یا غیر فعال کریں — body: {enabled?: boolean, mode?: "on" | "off" | "auto"}
POST /api/skills/executions مہارت چلائیں — body: {skillName, apiKeyId, input?, sessionId?}
GET /api/skills/executions تمام مہارتوں کے لیے عمل درآمد کی سرگزشت کی فہرست بنائیں (?apiKeyId= سے فلٹر کریں)

تصدیق: مینجمنٹ سیشن یا مینجمنٹ-اسکوپڈ API key درکار ہے۔

مکمل تفصیلات کے لیے مہارتوں کا فریم ورک دیکھیں۔


پلگ اِنز

OmniRoute پلگ اِنز (تھرڈ پارٹی ایکسٹینشنز) کا نظم کریں۔

Method Path Description
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 ریکوئسٹ ہیڈر کے ذریعے کیا جاتا ہے — فعال/غیر فعال کرنے کا کوئی مستقل انٹرفیس موجود نہیں ہے۔

Method Path Description
GET /api/guardrails رجسٹر شدہ گارڈ ریلز اور ان کی حالت (نام / فعال / ترجیح) کی فہرست بنائیں
POST /api/guardrails/test نمونہ ان پٹ پر پری-کال پائپ لائن کا ڈرائی رن کریں — body: {input, disabledGuardrails?}

تصدیق: مینجمنٹ سیشن درکار ہے۔

مکمل تفصیلات کے لیے سیکیورٹی > گارڈ ریلز دیکھیں۔



توثیق

چار اسناد کی اقسام (ڈیش بورڈ سیشن، مقامی CLI ٹوکن، oma_live_… رسائی ٹوکن، مینج اسکوپ والی API کلید) اور ان کے انفرنس کیز سے فرق کے لیے مینجمنٹ توثیق دیکھیں۔

  • ڈیش بورڈ کے راستے (/dashboard/*) auth_token کوکی استعمال کرتے ہیں
  • لاگ اِن محفوظ کردہ پاس ورڈ ہیش استعمال کرتا ہے؛ بصورتِ دیگر INITIAL_PASSWORD استعمال ہوتا ہے
  • requireLogin کو /api/settings/require-login کے ذریعے فعال یا غیر فعال کیا جا سکتا ہے
  • /v1/* راستوں کو REQUIRE_API_KEY=true ہونے پر اختیاری طور پر Bearer API کلید درکار ہوتی ہے
  • اس حوالہ میں "مینجمنٹ ٹوکن" / "مینجمنٹ اسکوپ والی API کلید" سے مراد اس گائیڈ میں دی گئی اقسام میں سے کوئی ایک ہے — یہ کسی غیر متعین اضافی خفیہ قسم کی طرف اشارہ نہیں کرتا

اہم تبدیلی (v3.8.0) — /api/v1/agents/tasks/* اور کول ڈاؤن مینجمنٹ کے اختتامی مقامات کے لیے اب مینجمنٹ توثیق (ڈیش بورڈ کی auth_token کوکی یا مینجمنٹ اسکوپ والی API کلید) درکار ہے۔ جو کلائنٹس پہلے ان راستوں کو بغیر توثیق کے کال کرتے تھے، انہیں 401 Unauthorized موصول ہوگا۔ 588a0333 (fix(auth): require management auth for agent and cooldown APIs) کمٹ دیکھیں۔