Skip to content

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

196 KB
Raw Blame

API Reference (اردو)

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


🌐 زبانیں: 🇺🇸 انگریزی | 🇪🇹 አማርኛ | 🇸🇦 العربية | 🇦🇿 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 سطح اور سب سے زیادہ استعمال ہونے والے انتظامی endpoints شامل ہیں؛ مشین کے لیے قابلِ مطالعہ docs/openapi.yaml اور src/app/api/ کے تحت موجود route tree جامع ماخذ ہیں۔

OpenAI سے مطابقت رکھنے والے مخصوص protocol اور provider capability matrix کے لیے، OPENAI_COMPATIBILITY.md دیکھیں۔


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


چیٹ کمپلیشنز

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

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

حسبِ ضرورت ہیڈرز

ہیڈر سمت وضاحت
X-OmniRoute-No-Cache درخواست کیش کو نظرانداز کرنے کے لیے true پر سیٹ کریں
x-omniroute-no-memory درخواست اس درخواست کے لیے میموری + مہارتوں کا ادخال چھوڑنے کی خاطر true پر سیٹ کریں (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 درخواست کسی واحد ماڈل کی درخواست کو اس کی id کے ذریعے ایک فراہم کنندہ کنکشن (اکاؤنٹ) سے منسلک کریں — فی درخواست اکاؤنٹ پننگ دیکھیں
X-OmniRoute-Cache جواب HIT یا MISS (غیر اسٹریمنگ)
X-OmniRoute-Idempotent جواب اگر نقل ہٹائی گئی ہو تو true
X-OmniRoute-Progress جواب اگر پیش رفت کی ٹریکنگ فعال ہو تو enabled
X-OmniRoute-Session-Id جواب OmniRoute کی جانب سے استعمال کردہ مؤثر سیشن ID
X-OmniRoute-Request-Id جواب درخواست کی باہمی ربط کی id (جب معلوم ہو)
X-OmniRoute-Version جواب OmniRoute بلڈ ورژن (ہمیشہ موجود)
X-OmniRoute-Cost-Saved جواب کسی HIT پر کیش کے ذریعے بچائے گئے USD (صرف کیش ہٹس)
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"}]}'
  • id کہاں تلاش کریں۔ ڈیش بورڈ میں فراہم کنندہ کا صفحہ کھولیں (Dashboard → Providers → ) اور کنکشن کی قطار میں موجود xxxxxxxx… id چِپ پر کلک کریں — اس سے مکمل کنکشن id کاپی ہو جاتی ہے۔
  • کون سی درخواستیں اسے تسلیم کرتی ہیں۔ /v1/chat/completions، /v1/messages اور /v1/responses پر واحد ماڈل کی درخواستیں (provider/model)۔ کومبوز ہیڈر کو نظر انداز کرتے ہیں: اس کے بجائے ہر کومبو مرحلے کے اپنے کنکشن کے ذریعے اس کے لیے ایک اکاؤنٹ پن کریں۔
  • پن سخت ہے، محض ترجیح نہیں۔ پن کردہ کنکشن خصوصی طور پر استعمال ہوتا ہے۔ درخواست کے اندر ناکامی اکاؤنٹ کا کول ڈاؤن ریکارڈ کرتی ہے، لیکن اسی فراہم کنندہ کے کسی دوسرے اکاؤنٹ پر منتقل نہیں ہوتی۔
  • کول ڈاؤن اور کوٹا پن کو جاری کر دیتے ہیں۔ جب پن کردہ کنکشن کول ڈاؤن میں ہو، اس کا کوٹا ختم ہو چکا ہو یا وہ کسی کوٹا پالیسی کے باعث بلاک ہو، تو بعد کی درخواستیں فراہم کنندہ کے دیگر کنکشنز پر بالکل اَن پن ٹریفک کی طرح منتقل ہو جاتی ہیں۔
  • نامعلوم یا غیر فعال ids ناکام ہو جاتی ہیں۔ ایسی id جو فراہم کنندہ کے فعال پول میں موجود نہ ہو (حذف شدہ، غیر فعال، یا کسی دوسرے فراہم کنندہ سے تعلق رکھنے والی) کوئی اہل اکاؤنٹ باقی نہیں چھوڑتی، لہٰذا درخواست خاموشی سے کہیں اور روٹ ہونے کے بجائے ناکام ہو جاتی ہے۔

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 (USD، مقررہ 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"}

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

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

ایک فعال لیز کا مالک اپنی موجودہ بائنڈنگ کے لیے واضح طور پر پرائیویسی-محفوظ ڈسپلے میٹا ڈیٹا کی درخواست کر سکتا ہے:

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

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

غلط کلید، غلط مالک، پرانی جنریشن، گمشدہ، میعاد ختم شدہ، جاری کردہ، اور غلط تلاشیاں سبھی کنکشن میٹا ڈیٹا کے بغیر ایک ہی 409 LEASE_FENCE_STALE خرابی واپس کرتی ہیں۔ ایک کلائنٹ جس نے صلاحیت-انتظار کا جواب حاصل کیا ہے اس کے پاس معائنہ کرنے کے لیے کوئی فعال بائنڈنگ نہیں ہے۔ جب روٹنگ ایک فعال لیز کو منتقل کرتی ہے، تو وہی جنریشن درست رہتی ہے اور اسٹیٹس جوہری طور پر نئی بائنڈنگ واپس کرتا ہے، کبھی بھی پرانی نہیں۔ موجودہ کلائنٹس غیر تبدیل شدہ رہتے ہیں کیونکہ حصول، تجدید، ریلیز، اور انتظار کے جوابات اپنی پچھلی شکلیں برقرار رکھتے ہیں۔

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

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

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

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

عارضی تنازع HTTP 429 کو Retry-After اور اس کے ساتھ واپس کرتا ہے:

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

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

x-omniroute-compression

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

قدر اثر
off اس درخواست کے لیے کوئی کمپریشن نہیں۔
default پینل سے ماخوذ ڈیفالٹ پروفائل (فعال پروفائل کو نظر انداز کرتا ہے)۔ لوسی انجن بند رہتے ہیں۔
safe صرف ڈیڈوپ اور وائٹ اسپیس فولڈنگ۔
allow-lossy اس درخواست کے لیے آپریٹر پلان کو برقرار رکھیں، بشمول خلاصے اور اسٹائل ری رائٹس۔
engine:<id> فعال ہونے پر ایک ہی انجن، مثلاً engine:rtk۔ اس انجن کے لیے فی درخواست آپٹ-ان۔
<combo> ایک نامزد کومبو، پہلے نام سے (کیس-غیر حساس) پھر ID سے مماثل۔

نوٹس:

  • نامعلوم اقدار کو نظر انداز کر دیا جاتا ہے (درخواست کبھی مسترد نہیں کی جاتی)؛ ریزولوشن عام آپریٹر کی ترجیح پر آ جاتا ہے۔
  • اگر متعدد کومبوز ایک نام کا اشتراک کرتے ہیں، تو ایک متعین میچ کے لیے کومبو id پاس کریں۔
  • ایک کومبو جس کا نام off یا default ہے اسے نام سے منتخب نہیں کیا جا سکتا (ان کلیدی الفاظ کی پہلے تشریح کی جاتی ہے)؛ ایسے کومبو کو اس کی ID سے حوالہ دیں۔
  • ماسٹر کمپریشن سوئچ ایک سخت گیٹ ہے: جب کمپریشن عالمی سطح پر غیر فعال ہو، تو یہ ہیڈر اسے فعال نہیں کر سکتا۔

لاگو شدہ پلان کو رسپانس ہیڈر میں واپس گونجایا جاتا ہے:

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۔

کیٹلاگ IDs کی شکل provider/model ہے (مثال: jina-ai/jina-embeddings-v5-omni-small)۔ رجسٹری میں موجود مختصر Jina ماڈل IDs (مثلاً 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) اور کبھی بھی embeddings یا 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 ان آبجیکٹس کو اسٹرنگ میں تبدیل نہیں کرتا اور نہ ہی مقامی image URLs کو حاصل کرتا ہے — Jina عوامی میڈیا خود حاصل کرتا ہے۔ اضافی Jina فیلڈز (task، normalized، truncate، embedding_type) فارورڈ کیے جاتے ہیں۔ صرف متن والے Jina SKUs اب بھی غیر متنی دستاویزات کو مسترد کرتے ہیں۔

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

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

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

  • Jina ملٹی موڈل ماڈلز: ہر اعلیٰ سطحی آئٹم ایک موڈیلٹی کلید والا آبجیکٹ بن جاتا ہے (text / image / audio / video / pdf)، جس میں اِن لائن میڈیا کے لیے data URIs استعمال ہوتے ہیں؛ فی اعلیٰ سطحی آئٹم ایک ویکٹر۔
  • Gemini Embedding 2 فیملی: ایک اعلیٰ سطحی array، content.parts (text یا inline_data) کے ساتھ، ایک واحد مقامی models/{model}:embedContent درخواست بن جاتا ہے۔
  • llama.cpp (llama-cpp/<model>، مقامی سرور پر لوڈ کیا گیا کوئی بھی ماڈل): معیاری text آئٹمز سادہ اسٹرنگز بن جاتے ہیں، جبکہ image / audio / video میں سے ہر ایک ایک {"content": [part]} آبجیکٹ بن جاتا ہے، جو اِن لائن ڈیٹا کے ساتھ llama-server کے چیٹ مواد کے حصے (image_url، input_audio بہ فارمیٹ wav / mp3 / flac، input_video) استعمال کرتا ہے؛ فی اعلیٰ سطحی آئٹم ایک ویکٹر۔ سرور کو لازماً --embedding --mmproj … کے ساتھ چلنا چاہیے؛ پروجیکٹر کے بغیر یہ خود میڈیا کو مسترد کر دیتا ہے۔ document معاونت یافتہ نہیں ہے۔
  • واضح موڈیلٹی میٹا ڈیٹا کے بغیر نامعلوم/ڈائنامک ماڈلز ساخت یافتہ ان پٹ کو HTTP 400 کے ساتھ مسترد کرتے ہیں۔
{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "input": [
    { "type": "text", "text": "A red bicycle" },
    {
      "type": "image",
      "source": { "type": "url", "url": "https://example.com/bicycle.png" }
    }
  ],
  "dimensions": 512,
  "encoding_format": "float"
}

غیر معاون ماڈل/موڈیلٹی امتزاج آئٹم کو تبدیل کرنے کے بجائے HTTP 400 واپس کرتے ہیں۔ پرانی اسٹرنگ/ٹوکن درخواستوں میں ان پٹ کے علاوہ توسیعی فیلڈز بدستور بغیر تبدیلی کے آگے بھیجے جاتے ہیں۔

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

تصویر بنانا

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

{
  "model": "openai/gpt-image-2",
  "prompt": "پہاڑوں کے اوپر ایک خوبصورت غروبِ آفتاب",
  "size": "1024x1024"
}

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

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

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

  • zenmux/openai/gpt-image-2، ZenMux کا OpenAI Images API استعمال کرتا ہے۔ اختیارات میں size، quality، n، output_format، output_compression، background، اور response_format شامل ہیں۔
  • دیگر ناشرین، جیسے zm/meta/muse-image-1.0، ZenMux کا Vertex 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 کے ذریعے کی جا سکتی ہے۔

یہ انٹیگریشن متن سے تصویر بنانے کی معاونت کرتا ہے، حوالہ جاتی تصویر میں ترمیم کی نہیں۔ Vertex آؤٹ پٹ کو data[].b64_json میں معمول پر لایا جاتا ہے؛ response_format: "url" ایک اپ اسٹریم HTTPS URL واپس کرتا ہے، یا جب صرف تصویری بائٹس دستیاب ہوں تو base64 ڈیٹا URL واپس کرتا ہے۔ خالی/فلٹر شدہ آؤٹ پٹس خالی کامیاب جواب کے بجائے خرابی واپس کرتے ہیں۔ ماڈل تک رسائی ZenMux اکاؤنٹ پر منحصر ہے۔ ZenMux کا Vertex API اور OpenAI Images API دیکھیں۔

# تمام تصویری ماڈلز کی فہرست دکھائیں
GET /v1/images/generations

دستاویز OCR

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

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

model ایک provider/model سابقے کے ذریعے OCR فراہم کنندہ منتخب کرتا ہے؛ صرف ماڈل id (مثلاً mistral-ocr-latest) اپنے رجسٹرڈ فراہم کنندہ سے منسلک ہو جاتی ہے، اور اگر model فراہم نہ کیا جائے تو پہلے سے طے شدہ Mistral (mistral-ocr-latest) استعمال ہوتا ہے۔ رجسٹرڈ فراہم کنندگان (open-sse/config/ocrRegistry.ts):

فراہم کنندہ id ماڈل id model کی قدر نوٹس
mistral mistral-ocr-latest mistral/mistral-ocr-latest (یا صرف mistral-ocr-latest) ہم وقت — واحد upstream کال سے جواب براہِ راست واپس کیا جاتا ہے۔
azure-document-intelligence prebuilt-read azure-document-intelligence/prebuilt-read غیر ہم وقت upstream (analyze + پولنگ) — ذیل میں دیکھیں۔
vertex-deepseek-ocr deepseek-ocr-maas vertex-deepseek-ocr/deepseek-ocr-maas ہم وقت، Vertex AI کے openapi/chat/completions پارٹنر endpoint کے ذریعے — توثیق/URL کے لیے ذیل میں دیکھیں۔

تینوں فراہم کنندگان ایک ہی Mistral طرز کی باڈی میں جواب دیتے ہیں:

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

Azure Document Intelligence کی پولنگ کا بہاؤ

Azure Document Intelligence کی analyze API غیر ہم وقت ہے: ابتدائی درخواست باڈی کے بجائے ایک Operation-Location ہیڈر واپس کرتی ہے، اور نتیجے کے لیے پولنگ کرنا ضروری ہوتا ہے۔ ہینڈلر (open-sse/handlers/ocr.ts) اس URL کو ہر سیکنڈ میں زیادہ سے زیادہ 30 کوششوں تک پول کرتا ہے، کسی غیر-ok پول جواب یا "failed" اسٹیٹس پر فوراً ناکام ہو جاتا ہے (پولنگ جاری نہیں رکھتا)، اور اگر کوششوں کی حد ختم ہونے کے بعد بھی کارروائی جاری ہو تو 504 واپس کرتا ہے۔ حتمی Azure جواب کو کال کرنے والے کو واپس کرنے سے پہلے Mistral میں استعمال ہونے والی اسی pages/markdown ساخت میں معمول پر لایا جاتا ہے، لہٰذا کلائنٹ کوڈ کو فراہم کنندہ کے لیے الگ خصوصی صورت سنبھالنے کی ضرورت نہیں ہوتی۔

Vertex AI DeepSeek OCR کی توثیق اور endpoint کا تعین

vertex-deepseek-ocr اسی Vertex AI توثیق کو دوبارہ استعمال کرتا ہے جس کی OmniRoute پہلے ہی چیٹ/تصویری ٹریفک (open-sse/executors/vertex.ts) کے لیے معاونت کرتا ہے: کنکشن کی API کلید یا تو Service Account JSON اسناد ہوتی ہے (جسے JWT-bearer بہاؤ کے ذریعے مختصر مدت کے OAuth رسائی ٹوکن سے تبدیل کیا جاتا ہے) یا پہلے سے جاری کردہ OAuth رسائی ٹوکن، جسے جوں کا توں استعمال کیا جاتا ہے۔ upstream endpoint URL، Vertex کا عمومی openapi/chat/completions پارٹنر endpoint ہے، جو کنکشن کے پروجیکٹ اور خطے سے بنایا جاتا ہے — واضح providerSpecificData.project/providerSpecificData.region کو ہمیشہ ترجیح دی جاتی ہے؛ بصورتِ دیگر پروجیکٹ Service Account JSON کے project_id سے اخذ کیا جاتا ہے اور خطے کی پہلے سے طے شدہ قدر us-central1 ہوتی ہے۔ دونوں کا تعین open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken، resolveVertexOcrBaseUrl) میں ہوتا ہے، جنہیں handleOcr کو بھیجنے سے پہلے src/app/api/v1/ocr/route.ts استعمال کرتا ہے۔


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

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

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

ماڈل id کے سابقے (?prefix=)

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

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

dual موڈ کے mirror کو query parameter کے بغیر بھی پہچانا جا سکتا ہے: اس میں primary id کی طرف اشارہ کرنے والا parent فیلڈ ہوتا ہے۔

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

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

GET /v1/models اختیاری دریافت کے فلٹرز قبول کرتا ہے۔ ان میں سے کسی کے بغیر response تبدیل نہیں ہوتا۔ یہ اس کیٹلاگ کو محدود کرتے ہیں جو caller پہلے ہی دیکھ سکتا ہے (API key کی permissions پہلے لاگو ہوتی ہیں)، اور یہ OpenAI طرز کی limit / after paging سے پہلے چلتے ہیں:

GET /v1/models?capability=vision&capability=tool_calling   # فہرست میں شامل ہر capability کا true ہونا ضروری ہے
GET /v1/models?capability=vision,reasoning&min_context=200000
GET /v1/models?kind=embedding                              # کیٹلاگ `type`؛ اس کے بغیر rows کو `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 اسی کیٹلاگ سے ایک مختصر، قطعی فہرست واپس کرتا ہے، جس پر وہی توثیق اور فی key visibility لاگو ہوتی ہے جو 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 ایک array یا comma-separated string قبول کرتے ہیں؛ max_output کا موازنہ max_output_tokens سے کیا جاتا ہے۔ نتائج پہلے owned_by، پھر id کے لحاظ سے ترتیب دیے جاتے ہیں۔ limit کا ڈیفالٹ 20 ہے اور 100 سے زیادہ اقدار کو 100 تک محدود کر دیا جاتا ہے۔ غلط JSON، نامعلوم فیلڈ یا غلط قدر HTTP 400 واپس کرتی ہے۔

انفرادی طور پر مخفی چیٹ ماڈلز

اپنے provider صفحے پر مخفی نشان زد ماڈل کو کیٹلاگ سے خارج کر دیا جاتا ہے اور واضح طور پر درخواست کیے جانے پر HTTP 404 / model_not_found کے ساتھ مسترد کر دیا جاتا ہے۔ یہ جانچ resolve شدہ provider اور model کو استعمال کرتی ہے، بشمول provider aliases، compatible-provider node prefixes، اور connection defaults۔ ایک combo مخفی targets کو چھوڑ دیتا ہے اور کسی visible sibling کو استعمال کر سکتا ہے؛ جب کوئی قابلِ عمل target باقی نہ رہے تو یہی error code واپس کرتا ہے۔ مخفی حیثیت ختم کرنا اگلی درخواست پر مؤثر ہو جاتا ہے۔ صرف image کے visibility overrides، اسی ID والے chat model کو مخفی نہیں کرتے۔

یہ انفرادی model setting، ماڈل exposure کی allow/deny فہرستوں سے الگ ہے، جو واضح dispatch برقرار رکھتے ہوئے کیٹلاگ اشتہار اور auto-routing candidates کو filter کرتی ہیں۔ API key کی model permissions آزادانہ طور پر لاگو رہتی ہیں۔ ڈیفالٹ catalog prefix mode بدستور dual ہے۔

بغیر thinking والے ماڈل variants

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

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

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


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

GET /api/v1/provider-plugin-manifest

یہ Bifrost، CLIProxyAPI، اور مستقبل کے سائڈ کار راؤٹرز کے زیرِ استعمال JSON-محفوظ فراہم کنندہ پلگ اِن مینی فیسٹ واپس کرتا ہے۔ جواب TypeScript فراہم کنندہ رجسٹری سے تیار کیا جاتا ہے اور دانستہ طور پر OAuth کلائنٹ سیکرٹس، رن ٹائم ماحول کی ریزولیوشن، ایگزیکیوٹر فنکشنز، درخواست کے ہیڈرز، اور اکاؤنٹ ڈیٹا کو شامل نہیں کرتا۔

اس اینڈ پوائنٹ کو اس وقت استعمال کریں جب کوئی سائڈ کار عمل سے باہر چلتا ہو اور براہِ راست open-sse/config/providerPluginManifestRegistry.ts درآمد نہ کر سکتا ہو۔


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

طریقہ راستہ فارمیٹ
POST /v1/chat/completions OpenAI
POST /v1/messages Anthropic
POST /v1/responses OpenAI Responses
POST /v1/embeddings OpenAI
POST /v1/images/generations OpenAI Images
POST /v1/images/edits OpenAI Images (ترمیم/اِن پینٹ)
POST /v1/videos/generations OpenAI طرز کی ویڈیو جنریشن
POST /v1/music/generations OpenAI طرز کی موسیقی جنریشن
POST /v1/audio/transcriptions OpenAI Audio (تقریر سے متن)
POST /v1/audio/speech OpenAI TTS (آڈیو باڈی واپس کرتا ہے)
POST /v1/rerank Cohere/Voyage طرز کی دوبارہ درجہ بندی
POST /v1/classify Jina درجہ بندی (api.jina.ai)
POST /v1/segment Jina سیگمینٹر (segment.jina.ai)
POST /v1/moderations OpenAI Moderations
GET /v1/models OpenAI
POST /v1/models/query فلٹر شدہ ماڈلز کی مختصر فہرست
POST /v1/messages/count_tokens Anthropic
GET /v1beta/models Gemini
POST /v1beta/models/{...path} Gemini generateContent
POST /v1/api/chat Ollama
GET /api/v1/vscode/{token}/ OpenAI کیٹلاگ کا عرف
GET /api/v1/vscode/{token}/models OpenAI ماڈلز کا عرف
POST /api/v1/vscode/{token}/chat/completions OpenAI ٹوکن شدہ عرف
POST /api/v1/vscode/{token}/responses OpenAI Responses کا ٹوکن شدہ عرف
POST /api/v1/vscode/{token}/api/chat Ollama کا ٹوکن شدہ عرف
GET /api/v1/vscode/{token}/api/tags Ollama ٹیگز کا ٹوکن شدہ عرف

تمام POST روٹس ایک ہی ساخت کی پیروی کرتے ہیں: Bearer your-api-key + Zod سے توثیق شدہ JSON باڈی (v1RerankSchema, v1ModerationSchema, v1AudioSpeechSchema، وغیرہ، src/shared/validation/schemas.ts دیکھیں)۔ اسکیما کی ناکامی پر 4xx واپس کیا جاتا ہے۔

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

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

# Jina درجہ بندی (Foundation API اسناد)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina سیگمینٹر
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina تلاش (s.jina.ai؛ فراہم کنندہ کے عرف: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# مواد کی نگرانی
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — audio/mpeg (یا مطلوبہ فارمیٹ) باڈی واپس کرتا ہے
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS کے لیے زبان اور آواز درکار ہیں: `language` کی ڈیفالٹ قدر "en" ہے؛ غائب
# آواز یا OpenAI کی اسٹاک آواز کا نام (alloy, nova, …) "Adrian" بن جاتا ہے
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# تصویر میں ترمیم (multipart)
POST /v1/images/edits  -F [email protected] -F prompt="..." -F [email protected]

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

ری رینک فراہم کنندہ نوڈز: POST /v1/rerank کی درخواستیں OpenAI سے مطابقت رکھنے والے فراہم کنندہ نوڈز (oMLX، vLLM، Infinity، کسی گیٹ وے کے پیچھے TEI، …) کو بھی بھیجی جاتی ہیں، جنہیں <node-prefix>/<model> کی صورت میں ایڈریس کیا جاتا ہے۔ لوپ بیک نوڈز (localhost، 127.0.0.1، 172.16.0.0/12) ہمیشہ اہل ہوتے ہیں، اور وہ میزبان نام بھی اہل ہوتے ہیں جنہیں آپریٹر OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS میں درج کرتا ہے (مثلاً Docker/Compose سروس کا نام، جیسے http://reranker:8080/v1؛ انہیں براہِ راست کال کیا جاتا ہے، کبھی بھی HTTP(S)_PROXY یا کسی کنکشن کی پن شدہ پراکسی کے ذریعے نہیں)۔ کسی بھی دوسرے میزبان پر موجود نوڈز — مثلاً LAN مشین یا Tailscale پیئر — صرف اسی وقت اہل ہوتے ہیں جب آپریٹر RERANK_REMOTE_PROVIDER_NODES فیچر فلیگ فعال کرے اور نوڈ کا بنیادی URL فراہم کنندہ کی آؤٹ باؤنڈ URL پالیسی (OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS / OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS) پر پورا اترے۔ میموری انجن کا ری رینک مرحلہ اس روٹ کو لوپ بیک کے ذریعے کال کرتا ہے، اس لیے یہی اصول میموری کی ترتیبات میں rerankProviderModel پر بھی لاگو ہوتا ہے۔

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

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

مخصوص فراہم کنندہ روٹس

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

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


Files API

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

طریقہ راستہ تفصیل
POST /v1/files فائل اپ لوڈ کریں (ملٹی پارٹ: file، purpose، expires_after[anchor]، expires_after[seconds]) — زیادہ سے زیادہ 512 MiB
GET /v1/files توثیق شدہ API کلید کی فائلوں کی فہرست حاصل کریں
GET /v1/files/[id] فائل کا میٹا ڈیٹا حاصل کریں
DELETE /v1/files/[id] فائل حذف کریں
GET /v1/files/[id]/content خام فائل باڈی کو واپس اسٹریم کریں

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


Batches API

OpenAI سے مطابقت رکھنے والی بیچ پروسیسنگ۔

طریقہ راستہ تفصیل
POST /v1/batches بیچ بنائیں — باڈی کی توثیق v1BatchCreateSchema کے ذریعے ہوتی ہے (input_file_id، endpoint، completion_window)
GET /v1/batches بیچز کی فہرست حاصل کریں
GET /v1/batches/[id] بیچ کی حالت + request_counts حاصل کریں
DELETE /v1/batches/[id] مکمل/ناکام بیچ حذف کریں
POST /v1/batches/[id]/cancel زیرِ عمل بیچ منسوخ کریں

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


تلاش API

ویب/تلاش فراہم کنندہ تجرید (Tavily، Brave، Exa، Serper، وغیرہ)۔

طریقہ راستہ وضاحت
GET /v1/search تشکیل کردہ تلاش فراہم کنندگان اور صلاحیتوں کی فہرست
POST /v1/search تلاش کی استفسار چلائیں — باڈی کی توثیق v1SearchSchema کے ذریعے ہوتی ہے، کیشنگ/یکجائی کی معاونت موجود ہے
GET /v1/search/analytics فی فراہم کنندہ ہٹ/تاخیر/کیش کے اعداد و شمار

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

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 اسکیما کے مطابق جانچا جاتا ہے، اور غلط قسم والی کلید خارج کر دی جاتی ہے۔ تصدیق، بنیادی URL، stream اور outputSchema سمیت کوئی بھی دوسری کلید نظر انداز کر دی جاتی ہے۔ دوسرے فراہم کنندگان کے زیرِ استعمال ہموار کلیدیں (cx، depth، ...) پہلے کی طرح کام کرتی ہیں۔

فراہم کنندہ بالائی سطح کی فیلڈز اندرونی
Exa type، category، userLocation، moderation، additionalQueries، objective، systemPrompt، compliance (ہموار ابتدائی اقدار)، startPublishedDate، endPublishedDate contents.{text, highlights, summary, extras, subpages, subpageTarget, livecrawlTimeout, maxAgeHours} کو طے شدہ { text: true, highlights: true } کے اوپر ضم کیا جاتا ہے
Tavily search_depth، chunks_per_source، time_range، start_date، end_date، include_published_date، filter_by_published_date، include_answer، include_raw_content، include_images، include_image_descriptions، include_favicon، include_domains_mode، language، filter_by_language، auto_parameters، exact_match، include_usage، safe_search —

عمومی فیلڈز کو ہمیشہ ترجیح حاصل ہوتی ہے: query، max_results، filters (ڈومینز)، country اور search_type سے اخذ کردہ موضوع۔ Exa پر، search_type: "news" کی صورت میں category: "news" برقرار رہتا ہے۔ Tavily، search_type: "finance" (topic: "finance") کو بھی قبول کرتا ہے۔

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

Exa کے نتائج میں id، highlight_scores، summary، subpages، entities اور extras کو provider_raw میں برقرار رکھا جاتا ہے۔ Tavily کے نتائج میں images اور favicon برقرار رکھے جاتے ہیں۔

لاگت کا حساب اب بھی ہموار رجسٹری costPerQuery ہے۔ Tavily میں search_depth: "advanced" کے لیے فی کال زیادہ کریڈٹس وصول کیے جاتے ہیں، اور یہ فرق usage.search_cost_usd میں ظاہر نہیں ہوتا۔


ویب فیچ API

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

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

طریقہ راستہ وضاحت
POST /v1/web/fetch کسی URL کو فیچ/اسکریپ کریں — باڈی کی توثیق v1WebFetchSchema کے ذریعے ہوتی ہے

توثیق: بیئرر API کلید (extractApiKey + isValidApiKey)۔ پالیسی enforceApiKeyPolicy کے ذریعے نافذ کی جاتی ہے۔

کوٹہ سے آگاہ فال بیک (#8297): جب کوئی واضح provider نہ دیا گیا ہو، تو پول (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search → parallel-search) کو مقررہ ترجیحی ترتیب (پہلے پُر کریں) میں آزمایا جاتا ہے — ریٹ-محدود مگر تشکیل شدہ فراہم کنندہ درخواست کو وہیں ختم کرنے کے بجائے چھوڑ دیا جاتا ہے، اور دوبارہ کوشش کے قابل/کوٹہ سے متعلق upstream ناکامی (HTTP 429 ہمیشہ؛ Firecrawl/Tavily/TinyFish کے کوٹہ طرز کے مفت درجات کے لیے 402/403 — Jina Reader کے لیے نہیں، اور سادہ 400 ناقص درخواست کے لیے کبھی نہیں) درخواست کے وقت اگلے ایسے فراہم کنندہ تک منتقل ہو جاتی ہے جسے ابھی آزمایا نہ گیا ہو اور جس کی اسناد دستیاب ہوں۔ جب پول میں موجود ہر فراہم کنندہ ختم ہو جائے، تو endpoint سابقہ عمومی 400 کے بجائے ایک واحد 429 (Retry-After ہیڈر کے ساتھ) واپس کرتا ہے۔ جب کسی واضح provider کی درخواست کی جائے، تو کوئی خاموش فال بیک نہیں ہوتا — ریٹ-محدود یا ناکام واضح فراہم کنندہ اپنی ہی خرابی ظاہر کرتا ہے (ریٹ-محدود ہونے پر 429، بصورتِ دیگر upstream اسٹیٹس)۔


WebSocket اسٹریمنگ

GET /v1/ws?handshake=1

WebSocket اپ گریڈ ہینڈ شیک کی توثیق کرتا ہے اور وائر پروٹوکول کے مثالی پیغامات (request، cancel) واپس کرتا ہے۔ اصل WS فریمز کو Next.js روٹ ٹیبل سے باہر شامل شدہ WS سرور سنبھالتا ہے۔

توثیق: ہینڈ شیک کے دوران Bearer API کلید۔

WebSocket کے ذریعے Responses API (صرف codex)

# HTTP API کے طور پر وہی host:port (ڈیفالٹ 20128)؛ کنکشن اپ گریڈ کریں:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (یا: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

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

Responses-API-over-WebSocket پراکسی صرف codex (ChatGPT بیک اینڈ) سے منسلک ہے۔ یہ API/ڈیش بورڈ ہی کی پورٹ پر /v1/responses، /responses، اور /api/v1/responses راستوں پر سنتی ہے۔ پہلے response.create فریم پر یہ اندرونی codex-responses-ws برج کے ذریعے توثیق اور تیاری کرتی ہے، ایک codex OAuth کنکشن منتخب کرتی ہے، اور wreq-js ٹرانسپورٹ کے ذریعے wss://chatgpt.com/backend-api/codex/responses تک ٹنل بناتی ہے۔ غیر codex ماڈلز مسترد کر دیے جاتے ہیں (codex_ws_provider_required)۔ کوٹہ شیئر روٹنگ کے لیے model: "qtSd/<group>/codex/<model>" استعمال کریں۔ نفاذ app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts میں ہے۔

توثیق: ہینڈ شیک کے دوران Bearer API کلید۔ شامل شدہ HTTP سرور (server-ws.mjs) کا فعال نقطۂ آغاز ہونا ضروری ہے (جب app/server-ws.mjs موجود ہو تو بطور ڈیفالٹ یہی ہوتا ہے)۔

ماڈل id: سادہ ChatGPT id استعمال کریں (codex/ سابقے کے بغیر)

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

OpenAI Codex CLI کی ترتیب

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

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

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # آخر میں سلیش نہیں؛ WS URL اخذ کیا جاتا ہے (پروڈکشن میں https/wss استعمال کریں)
wire_api = "responses"                    # فروری 2026 سے واحد معاون قدر
supports_websockets = true                # Responses-over-WS ٹرانسپورٹ فعال کرتا ہے
env_key = "OMNIROUTE_API_KEY"             # OmniRoute API کلید (Bearer) رکھتا ہے
export OMNIROUTE_API_KEY=sk-...           # ایک OmniRoute API کلید (اگر REQUIRE_API_KEY=false ہو تو کوئی بھی کلید)
codex exec "Responda apenas: PONG"

CLI، base_url + /responses کو WebSocket میں اپ گریڈ کرتا ہے اور OmniRoute اسے منتخب کردہ codex OAuth کنکشن تک ٹنل کرتا ہے۔ مقامی سرور کے خلاف ابتدا سے انتہا تک توثیق شدہ: ChatGPT، codex.rate_limits + response.created واپس کرتا ہے اور تکمیل کو اسٹریم کرتا ہے۔


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

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

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


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

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

# متنی صورت (تاریخی معاہدہ — ٹرمینل کے لیے سادہ متن)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# ساختی صورت — جسے UI استعمال کرتا ہے
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

کلید کے لیے allowUsageCommand فعال ہونا ضروری ہے (یہ بطور ڈیفالٹ غیر فعال ہوتا ہے — ڈیش بورڈ کا API-key مینیجر اسے ہر کلید کے لیے الگ سے تبدیل کرتا ہے)۔ اس کے بغیر اینڈ پوائنٹ 403 کے ساتھ جواب دیتا ہے۔

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

{
  "allowed": true,
  // صرف اس وقت موجود ہوتا ہے جب کلید نے فی کلید استعمال کی حدود (یومیہ/ہفتہ وار USD) اختیار کی ہوں:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // منتخب فراہم کنندہ کے کوٹے کا اسنیپ شاٹ، یا اگر ابھی تک کچھ کیش نہ ہوا ہو تو null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // ہر کنکشن کا اسنیپ شاٹ، تاکہ UI متعدد فراہم کنندگان کو ساتھ ساتھ دکھا سکے:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

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

توثیق: کالر کی اپنی Bearer API کلید، جس کی isValidApiKey کے ذریعے توثیق کی جاتی ہے — یہ انتظامی سطح (/api/keys/…) نہیں ہے، جو requireManagementAuth کے پیچھے ہی رہتی ہے۔

خام بمقابلہ کٹ آف کے مطابق ایڈجسٹ شدہ کوٹے کے فیصد

/api/usage/om-usage استعمال کرتے وقت کالرز کو سادہ متنی آؤٹ پٹ اور ساختی JSON آؤٹ پٹ میں پیش کیے گئے فیصد کے درمیان فرق کو مدِنظر رکھنا چاہیے:

پہلو سادہ متنی فارمیٹ (/api/usage/om-usage / @@om-usage) JSON فارمیٹ (?format=json)
آؤٹ پٹ فیلڈ NN% left (مثلاً، 20% left) provider.quotas / providers[].quotas
پیمائش کٹ آف کے مطابق ایڈجسٹ شدہ قابلِ استعمال گنجائش: کٹ آف حد سے زیادہ باقی صلاحیت خام اپ اسٹریم کوٹا: فراہم کنندہ کی غیر ایڈجسٹ شدہ پیمائش
کٹ آف اسکیلنگ effectiveRemainingPercent() کے ذریعے اسکیل کی جاتی ہے تاکہ محفوظ ذخیرہ 0% left دکھائے کوئی نہیں (فراہم کنندہ کی اطلاع کے مطابق خام اسنیپ شاٹ اقدار)
حد کا ڈیٹا دکھائے گئے فیصد میں شامل ہوتا ہے ہر کنکشن کے quotaWindowThresholds میں محفوظ ہوتا ہے (یا سرور ڈیفالٹس)
بنیادی صارف انٹرایکٹو 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 اقدار پڑھنے سے اصل اپ اسٹریم کھپت ظاہر ہوگی (اوپر دی گئی مثال میں 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 ریسپانس ہیڈر چیک کرنا چاہیے:

قدر مطلب
synthetic جواب کیش سے فراہم کیا گیا؛ تاخیر حقیقی upstream وقت نہیں ہے
(غیر موجود) حقیقی upstream کال سے حاصل کردہ جواب

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

API کلیدیں cacheDefaultMode کے ذریعے سیمنٹک کیش سے پڑھنے کو ترک کر سکتی ہیں:

قدر طرزِ عمل
legacy کیش کا معمول کا طرزِ عمل (ڈیفالٹ)
bypass کیش lookup مکمل طور پر چھوڑ دیں؛ ہمیشہ upstream کو کال کریں

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

{ "cacheDefaultMode": "bypass" }

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

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

X-OmniRoute-No-Cache: true

ڈیش بورڈ اور انتظام

انتظامی روٹس (/api/*، عوامی auth/login کے علاوہ) عام inference API keys کے ذریعے مجاز نہیں ہوتے۔ اسناد کی اقسام، scopes، اور curl کی مثالوں کے لیے ملاحظہ کریں: انتظامی توثیق۔

توثیق

Endpoint Method Description
/api/auth/login POST لاگ اِن
/api/auth/logout POST لاگ آؤٹ
/api/settings/require-login GET/POST لاگ اِن کی حالت (GET، عوامی)۔ POST پاس ورڈ مقرر کرتا ہے / لاگ اِن کو فعال یا غیر فعال کرتا ہے: پاس ورڈ موجود ہونے کے بعد صرف آپریٹر کے لیے (ڈیش بورڈ سیشن، مقامی CLI، یا لاگ اِن غیر فعال — API keys اور oma_ tokens کو 403 ملتا ہے)؛ ڈیش بورڈ سیشن پاس ورڈ تبدیل کرنے کے لیے currentPassword بھیجتا ہے

فراہم کنندہ کا انتظام

Endpoint Method Description
/api/providers GET/POST فراہم کنندگان کی فہرست دیکھیں / نیا فراہم کنندہ بنائیں
/api/providers/[id] GET/PUT/DELETE فراہم کنندہ کا انتظام کریں
/api/providers/[id]/test POST فراہم کنندہ کے کنکشن کی جانچ کریں
/api/providers/[id]/models GET فراہم کنندہ کے ماڈلز کی فہرست دیکھیں
/api/providers/validate POST فراہم کنندہ کی کنفیگریشن کی توثیق کریں
/api/providers/bulk POST ایک فراہم کنندہ کے لیے API keys بڑی تعداد میں شامل کریں
/api/providers/import POST parse شدہ CSV/JSON فائل سے مختلف النوع فراہم کنندگان کی فہرست درآمد کریں (#6836)؛ ہر قطار کے جزوی ناکامی کے نتائج
/api/provider-nodes* Various فراہم کنندہ کے nodes کا انتظام
/api/provider-models GET/POST/PUT/PATCH/DELETE حسبِ ضرورت ماڈلز اور فی ماڈل overrides (شامل کرنا، اپ ڈیٹ کرنا، چھپانا/دکھانا، حذف کرنا)
/api/provider-models/validate-and-add POST انتظامی توثیق کے ساتھ، اختیاری سخت کنکشن توثیق اور اٹامک حسبِ ضرورت ماڈل رجسٹریشن؛ ماڈل کی توثیق دیکھیں

مطابقت پذیر/درآمد شدہ ماڈلز کے لیے، PUT /api/provider-models، provider، modelId، اور maxOutputTokenOverride قبول کرتا ہے: ایک مثبت عدد دستی output-token حد مقرر کرتا ہے، اور null اسے صاف کر کے ڈیفالٹ بحال کرتا ہے۔ GET /api/provider-models?provider=<provider> یہ اقدار modelOutputOverrides میں واپس کرتا ہے، بشمول ان ماڈلز کے جن کے لیے custom-model row موجود نہیں۔ override، runtime کی max_output_tokens صلاحیت استعمال کرتا ہے اور ماڈل کی دوبارہ مطابقت پذیری کے بعد بھی برقرار رہتا ہے۔ OpenAI-compatible فراہم کنندہ کا صفحہ یہی ترمیم/صاف کرنے کے controls فراہم کرتا ہے اور واضح vision support والے ماڈلز کو نشان زد کرتا ہے۔

حسبِ ضرورت Chat Completions nodes، واضح reasoning opt-outs کو upstream backend کے مطابق ڈھالتے ہیں۔ کنکشن کی کامیاب جانچ ہر عین model ID کے لیے خودکار طور پر chat-template controls منتخب کرتی ہے جس کی /models entry کسی تسلیم شدہ owned_by قدر کو ثابت کرتی ہو: vllm، sglang، یا llamacpp۔ شفاف OpenAI-compatible wrappers اصل model entry کو nested openai object کے اندر محفوظ رکھ سکتے ہیں؛ شناخت اس طرح کے زیادہ سے زیادہ تین envelopes کی پیروی کرتی ہے۔ غائب، نامعلوم، یا متضاد ملکیت والے ماڈلز OpenAI کا معمول کا طرزِ عمل برقرار رکھتے ہیں۔ شناخت موجودہ catalog request کو دوبارہ استعمال کرتی ہے، کوئی completion tokens تخلیق نہیں کرتی، اور connection endpoint تبدیل ہونے پر منسوخ ہو جاتی ہے۔

ایسے backend کے لیے یہ طرزِ عمل مستقل کرنے کے لیے جو یہ metadata ظاہر نہیں کرتا، موجودہ جزوی فراہم کنندہ update API استعمال کریں:

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

یہ باڈی PUT /api/providers/<connection-id> کے ساتھ بھیجیں۔ اس کنکشن پر، none کی صریح استدلالی کوشش chat_template_kwargs.thinking=false اور chat_template_kwargs.enable_thinking=false کے طور پر بھیجی جاتی ہے۔ صریح مقامی ٹیمپلیٹ اقدار حتمی اختیار رکھتی ہیں، سوائے اس کے کہ سرور کی جانب کا کوئی استدلالی اصول کسی کوشش کو لازمی قرار دے۔ یہ ترتیب صرف اس وقت لاگو ہوتی ہے جب کوئی حسبِ ضرورت OpenAI سے ہم آہنگ کنکشن Chat Completions باڈی بھیجتا ہے؛ Responses درخواستیں اور عام فراہم کنندگان اپنی مقامی درخواست کی ساخت برقرار رکھتے ہیں۔ عام OpenAI reasoning_effort کو بلا تبدیلی آگے بھیجنا لازمی بنانے کے لیے reasoningControl کو openai پر سیٹ کریں، یا خودکار تشخیص استعمال کرنے کے لیے اسے شامل نہ کریں/null پر سیٹ کریں۔

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

OAuth کے بہاؤ

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

روٹنگ اور کنفیگریشن

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

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

اینڈ پوائنٹ طریقہ وضاحت
/api/usage/history GET استعمال کی تاریخ
/api/usage/logs GET استعمال کے لاگز
/api/usage/request-logs GET درخواست کی سطح کے لاگز
/api/usage/[connectionId] GET ہر کنکشن کا استعمال
/api/usage/token-limits GET/POST/DELETE ہر API کلید کے لیے ٹوکن کی حد کے بجٹس
/api/usage/model-latency-stats GET ہر فراہم کنندہ/ماڈل کے لیے گردشی تاخیر کا مجموعی ڈیٹا (اوسط/p50/p95/p99، کامیابی کی شرح)؛ فلٹرز: windowHours/minSamples/maxRows/provider/model (#6873)
/api/usage/cache-health GET call_logs پر پرامپٹ کیش کی صحت کا خلاصہ — تحریر/مطالعہ تناسب، p50/p90/p99 تحریری حجم کی تقسیم، بھاری تحریر کا ارتکاز، ہر ماڈل کی علیحدہ تفصیل، اور healthy/degraded/thrash/no-data فیصلہ؛ کوئری پیرامیٹرز range (1h|24h|7d|30d، ڈیفالٹ 24h) اور اختیاری model (#8827)

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

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

فیلڈ قسم نوٹس
name اسٹرنگ، 1-200 حروف
isActive بولین
isBanned بولین
expiresAt ISO 8601 تاریخ و وقت یا null null میعاد ختم ہونے کی تاریخ کو صاف کر دیتا ہے
modelAccessMode all | restricted جب موڈ all ہو تو allowedModels خالی ہونا چاہیے
allowedModels, blockedModels اسٹرنگز کی اَرے، زیادہ سے زیادہ 1000
allowedCombos اسٹرنگز کی اَرے، زیادہ سے زیادہ 500 یہ محدود کرتا ہے کہ کلید کن کومبوز کو کال کر سکتی ہے؛ براہِ راست ماڈلز modelAccessMode / allowedModels کے زیرِ انتظام ہوتے ہیں
connectionAccessMode all | restricted restricted کی صورت میں allowedConnections غیر خالی، اور all کی صورت میں خالی ہونا چاہیے
allowedConnections UUIDs کی اَرے، زیادہ سے زیادہ 100
allowAutoCombos بولین false اس کلید کے ساتھ auto/* ماڈلز کی درخواستیں مسترد کرتا ہے؛ وہ کلیدیں جنہوں نے اسے کبھی سیٹ نہیں کیا، اجازت یافتہ ہیں
catalogScope all | combos | models یہ طے کرتا ہے کہ GET /v1/models اس کلید کے لیے کیا فہرست دکھاتا ہے (صرف کومبوز، صرف ماڈلز، یا دونوں)؛ یہ اس بات کو تبدیل نہیں کرتا کہ کلید کیا کال کر سکتی ہے
forcedModel زیادہ سے زیادہ 300 حروف کی اسٹرنگ، یا null چیٹ درخواستوں کو X-Route-Model اور body.model پر ترجیح دیتے ہوئے اس ماڈل/کومبو کی طرف روٹ کرتا ہے؛ کلید کی حدود پھر بھی لاگو رہتی ہیں
noLog, autoResolve بولین
throttleDelayMs عددِ صحیح، 0-300000
maxSessions عددِ صحیح، 0-10000
rateLimits { limit, window } کی اَرے (مثبت اعدادِ صحیح، زیادہ سے زیادہ 50) یا null null حدود کو صاف کر دیتا ہے
accessSchedule شیڈول آبجیکٹ یا null null شیڈول کو صاف کر دیتا ہے
scopes اسٹرنگز کی اَرے، زیادہ سے زیادہ 32
allowedEndpoints اسٹرنگز کی اَرے، زیادہ سے زیادہ 20
streamDefaultMode legacy | json
cacheDefaultMode legacy | bypass فی کلید کیش بائی پاس دیکھیں
compressionEnabled بولین
codexServiceMode Codex سروس موڈز میں سے ایک
disableNonPublicModels boolean
allowUsageCommand boolean
usageLimitEnabled boolean
dailyUsageLimitUsd, weeklyUsageLimitUsd number >= 0 یا null
chaosModeEnabled boolean
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'

ترتیبات

اینڈ پوائنٹ طریقہ تفصیل
/api/settings GET/PUT/PATCH عمومی ترتیبات۔ سیکیورٹی پالیسی کی کلیدوں (requireLogin، newPassword، oidc*، corsOrigins، bruteForceProtection) کے لیے currentPassword اور آپریٹر کی اسناد درکار ہیں — API کلیدوں اور oma_ ٹوکنز کو 403 ملتا ہے؛ ہر تبدیلی کے لیے رسائی ٹوکن کا admin دائرۂ کار درکار ہے
/api/settings/proxy GET/PUT نیٹ ورک پراکسی کی تشکیل
/api/settings/proxy/test POST پراکسی کنکشن کی جانچ کریں
/api/settings/ip-filter GET/PUT IP اجازت فہرست/بلاک فہرست
/api/settings/thinking-budget GET/PUT سوچنے/استدلال کی درخواست کو دوبارہ لکھنے کا موڈ (بلا تبدیلی / خودکار اخراج / حسبِ ضرورت / موافق)۔ کمپریشن سے آزاد ہے۔ THINKING_BUDGET.md دیکھیں۔
/api/settings/system-prompt GET/PUT عالمی سسٹم پرامپٹ
/api/settings/compression GET/PUT عالمی کمپریشن کی تشکیل
/api/settings/purge-request-history POST درخواست لاگ کی قطاریں اور مقامی کال لاگ کے باقیات صاف کریں

سیاق و سباق اور کمپریشن

اینڈ پوائنٹ میتھڈ تفصیل
/api/compression/preview POST off/lite/standard/aggressive/ultra/RTK/stacked کمپریشن کا پیش منظر
/api/compression/language-packs GET دستیاب Caveman لینگویج پیکس کی فہرست
/api/compression/rules GET Caveman قواعد کے میٹا ڈیٹا کی فہرست
/api/context/caveman/config GET/PUT Caveman کے لیے مخصوص ترتیبات کا متبادل نام
/api/context/rtk/config GET/PUT RTK کے لیے مخصوص ترتیبات، بشمول حسبِ ضرورت فلٹرز اور خام آؤٹ پٹ برقرار رکھنا
/api/context/rtk/filters GET RTK فلٹر کیٹلاگ اور حسبِ ضرورت فلٹر کی تشخیصی معلومات
/api/context/rtk/test POST متنی پے لوڈ پر RTK پیش منظر/ٹیسٹ چلائیں
/api/context/rtk/raw-output/[id] GET پوائنٹر id کے ذریعے محفوظ کردہ مخفی خام آؤٹ پٹ پڑھیں
/api/context/combos GET/POST کمپریشن کومبو کی فہرست/تخلیق
/api/context/combos/[id] GET/PUT/DELETE کمپریشن کومبو کی تفصیل/تجدید/حذف
/api/context/combos/[id]/assignments GET/PUT کمپریشن کومبوز کو روٹنگ کومبوز تفویض کریں
/api/context/analytics GET کمپریشن اینالیٹکس کا متبادل نام

نگرانی

اینڈ پوائنٹ میتھڈ تفصیل
/api/sessions GET فعال سیشنز کی نگرانی
/api/rate-limits GET فی اکاؤنٹ شرح کی حدود
/api/monitoring/health GET صحت کی جانچ + فراہم کنندہ کا خلاصہ (catalogCount، configuredCount، activeCount، monitoredCount)۔ انتظامی منظر میں credentialHealth شامل ہے: پروب کیش اسکیلرز، جب failed>0 ہو تو failedConnections، اور staleDbNonOkCount (SQLite کا چسپاں test_status، گیج نہیں)۔ MONITORING_GUIDE.md دیکھیں۔
/api/cache/stats GET/DELETE کیش کے اعداد و شمار / صاف کرنا
/api/modality-bridge/stats GET اِن میموری attempts، کامیابیاں/bridged، ناکامیاں، کیش ہٹس، totalLatencyMs، latencySamples، نمونوں کی تعداد کی بنیاد پر averageLatencyMs، اور آخری استعمال کا وقت (دوبارہ شروع ہونے پر ری سیٹ؛ انتظامی توثیق)
/api/modality-bridge/video/runtime GET انتظامی توثیق/پروب سے پہلے سخت قابلِ اعتماد loopback جانچ؛ صاف شدہ FFmpeg/ffprobe دستیابی اور ورژنز (no-store)
/api/modality-bridge/video/extract POST اندرونی، توثیق شدہ، قابلِ اعتماد loopback بائٹ بروکر؛ 50 MiB اِن پٹ، محدود قطار/32 MiB آؤٹ پٹ، 503 گنجائش، 499 منقطع ہونا، 504 آخری مہلت؛ یہ عوامی اپ لوڈ API نہیں ہے

بیک اپ اور برآمد/درآمد

Endpoint Method Description
/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) عام انتظامی تصدیق برقرار رکھتے ہیں۔

کلاؤڈ ہم وقت سازی

Endpoint Method Description
/api/sync/cloud Various کلاؤڈ ہم وقت سازی کی کارروائیاں
/api/sync/initialize POST ہم وقت سازی شروع کریں
/api/cloud/* Various کلاؤڈ کا انتظام

ٹنلز

Endpoint Method Description
/api/tunnels/cloudflared GET ڈیش بورڈ کے لیے Cloudflare Quick Tunnel کی تنصیب/رن ٹائم کی حالت پڑھیں
/api/tunnels/cloudflared POST Cloudflare Quick Tunnel کو فعال یا غیر فعال کریں (action=enable/disable)
/api/tunnels/ngrok GET ڈیش بورڈ کے لیے ngrok Tunnel کی رن ٹائم حالت پڑھیں
/api/tunnels/ngrok POST ngrok Tunnel کو فعال یا غیر فعال کریں (action=enable/disable)

CLI ٹولز

Endpoint Method Description
/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 ایجنٹس

Endpoint Method Description
/api/acp/agents GET حالت سمیت تمام دریافت شدہ ایجنٹس (بلٹ اِن + حسبِ ضرورت) کی فہرست
/api/acp/agents POST حسبِ ضرورت ایجنٹ شامل کریں یا دریافت کیش تازہ کریں
/api/acp/agents DELETE id کوئری پیرامیٹر کے ذریعے حسبِ ضرورت ایجنٹ ہٹائیں

GET جواب میں agents[] (id، name، binary، version، installed، protocol، isCustom) اور summary (total، installed، notFound، builtIn، custom) شامل ہیں۔

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

Endpoint Method Description
/api/resilience GET/PATCH درخواست کی قطار، کنکشن کول ڈاؤن، فراہم کنندہ بریکر، اور انتظار کی ترتیبات حاصل/اپ ڈیٹ کریں
/api/resilience/reset POST فراہم کنندہ سرکٹ بریکرز ری سیٹ کریں
/api/resilience/model-cooldowns GET فعال فی-(فراہم کنندہ، کنکشن، ماڈل) لاک آؤٹس کو باقی وقت کے لحاظ سے مرتب کر کے فہرست بنائیں
/api/resilience/model-cooldowns DELETE ماڈل لاک آؤٹ صاف کریں — باڈی {provider, model} یا سب کچھ مٹانے کے لیے {all: true}
/api/rate-limits GET فی اکاؤنٹ شرح کی حد کی حالت
/api/rate-limit GET عالمی شرح کی حد کی تشکیل

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

جائزے

Endpoint Method Description
/api/evals GET/POST جائزہ مجموعوں کی فہرست / جائزہ چلائیں

پالیسیاں

Endpoint Method Description
/api/policies GET/POST/DELETE روٹنگ پالیسیوں کا انتظام کریں

تعمیل

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

v1beta (Gemini سے ہم آہنگ)

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

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

داخلی / سسٹم APIs

اینڈ پوائنٹ طریقہ تفصیل
/api/init GET ایپلیکیشن کی ابتدا کی جانچ (پہلی بار چلانے پر استعمال ہوتا ہے)
/api/tags GET Ollama سے ہم آہنگ ماڈل ٹیگز (Ollama کلائنٹس کے لیے)
/api/restart POST سرور کو مناسب طریقے سے دوبارہ شروع کرنا
/api/shutdown POST سرور کو مناسب طریقے سے بند کرنا
/api/system/env/repair POST OAuth فراہم کنندہ کے ماحولیاتی متغیرات کی مرمت
/api/system/version GET موجودہ/تازہ ترین ورژن، اپ ڈیٹ کی حالت، ریلیز چینل
/api/system/version POST تازہ ترین ورژن پر تعیناتی سے آگاہ اپ ڈیٹ شروع کرنا

نوٹ: یہ اینڈ پوائنٹس سسٹم کے ذریعے داخلی طور پر یا Ollama کلائنٹ مطابقت کے لیے استعمال ہوتے ہیں۔ عموماً آخری صارفین انہیں براہ راست استعمال نہیں کرتے۔

OAuth ماحول کی مرمت (v3.6.1+)

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

{
  "provider": "claude-code"
}

کسی مخصوص فراہم کنندہ کے غائب یا خراب شدہ OAuth ماحولیاتی متغیرات کی مرمت کرتا ہے۔ نتیجے میں یہ واپس ملتا ہے:

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

ورژن اور ریلیز چینل

GET /api/system/version

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

چینل ماڈل (latest = 4.0 GA تک v3، next = rc، nightly = develop بلڈز، lts = 4.0 GA کے بعد 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 "[email protected]" \
  -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۔


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

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

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

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


Combo کا انتظام

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

طریقہ راستہ وضاحت
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 کلید؛ صرف استنتاج کے لیے API کلیدوں کو 403 ملتا ہے۔ /v1/quotas/check اور /v1/issues/report بھی دیکھیں۔


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

OmniRoute صارفین کی جانب سے ریموٹ طور پر انجام دیے جانے والے کلاؤڈ ایجنٹ ٹاسکس (Claude Code، Codex Cloud، OpenHands، وغیرہ)۔

طریقہ راستہ تفصیل
GET /api/v1/agents/tasks ٹاسکس کی فہرست — اختیاری ?provider=، ?status=، ?limit= (1–500، ڈیفالٹ 50)
POST /api/v1/agents/tasks ٹاسک بنائیں — باڈی کی توثیق CreateCloudAgentTaskSchema کے ذریعے ہوتی ہے (providerId، prompt، source، options?)۔ ٹاسک انویلپ کے ساتھ 201 واپس کرتا ہے
DELETE /api/v1/agents/tasks?id=... ایک ٹاسک حذف کریں
GET /api/v1/agents/tasks/[id] ٹاسک پڑھیں — جب external_id سیٹ ہو تو اپ اسٹریم کلاؤڈ ایجنٹ سے اسٹیٹس کو ہم وقت طور پر ریفریش کرتا ہے
POST /api/v1/agents/tasks/[id] امتیازی ایکشن: {action: "approve"}، {action: "message", message}، یا {action: "cancel"}
DELETE /api/v1/agents/tasks/[id] id کے ذریعے ایک مخصوص ٹاسک حذف کریں

توثیق: ہر طریقے پر مینجمنٹ توثیق درکار ہے (requireCloudAgentManagementAuth)۔ v3.8.0 سے پہلے یہ غیر توثیق شدہ تھے — اس بریکنگ تبدیلی کے لیے commit 588a0333 دیکھیں۔

# ایک Claude Code کلاؤڈ ٹاسک بنائیں
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

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

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

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

توثیق: ہر روٹ پر مینجمنٹ سیشن/API کلید درکار ہے (requireManagementAuth)۔

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


لچک پذیری (توسیعی)

OmniRoute عارضی ناکامی سے نمٹنے کے تین آزاد طریقۂ کار فراہم کرتا ہے؛ ذیل میں دیے گئے انتظامی endpoints آپریٹرز کو ان کی حالت پڑھنے اور انہیں override کرنے کی سہولت دیتے ہیں:

دائرہ حالت کا ذخیرہ پڑھنا ری سیٹ / صاف کرنا
فراہم کنندہ breaker domain_circuit_breakers + in-memory /api/monitoring/health POST /api/resilience/reset
کنکشن cooldown فراہم کنندہ کے کنکشنز پر rateLimitedUntil /api/rate-limits, /api/providers/[id] (ضرورت پڑنے پر دوبارہ فعال ہوتا ہے؛ فراہم کنندہ کے PUT کے ذریعے صاف کریں)
ماڈل lockout in-memory ماڈل دستیابی رجسٹری GET /api/resilience/model-cooldowns DELETE /api/resilience/model-cooldowns

PATCH /api/resilience، providerBreaker.oauth اور providerBreaker.apikey کے تحت فراہم کنندہ breaker overrides قبول کرتا ہے۔ ہر پروفائل degradationThreshold، failureThreshold، اور resetTimeoutMs کی معاونت کرتا ہے؛ یہی فیلڈز Dashboard → Settings → Resilience میں بھی دستیاب ہیں۔

# کسی ایک ماڈل کا lockout صاف کریں
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"}'

# تمام lockouts صاف کریں
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

مکمل تصوراتی حوالہ اور breaker کی طے شدہ اقدار کے لیے: CLAUDE.md → "لچک پذیری کی runtime حالت" دیکھیں۔


مہارتیں

OmniRoute کو حسبِ ضرورت قابلِ عمل handlers کے ذریعے وسعت دینے کے لیے مہارتوں کا فریم ورک، نیز marketplace integrations۔

طریقہ راستہ تفصیل
GET /api/skills نصب شدہ مہارتوں کی فہرست — ?q=، ?mode=on|off|auto، ?source=skillsmp|skillssh|local کے ذریعے قابلِ فلٹر، اور صفحات میں منقسم
GET /api/skills/[id] ایک مہارت حاصل کریں
PUT /api/skills/[id] مہارت اپ ڈیٹ کریں (نام، تفصیل، mode، schema، handler، tags)
DELETE /api/skills/[id] ایک مہارت اَن انسٹال کریں
POST /api/skills/install raw manifest سے مہارت نصب کریں — body: {name, version, description, schema:{input, output}, handlerCode, apiKeyId?}
GET /api/skills/executions حالیہ مہارت executions کی فہرست (inputs/outputs/duration کے ساتھ audit trail)
GET /api/skills/marketplace?q=... SkillsMP marketplace سے تلاش/مقبول فہرست (skillsmpApiKey setting درکار ہے)
POST /api/skills/marketplace/install SkillsMP سے id کے ذریعے مہارت نصب کریں
GET /api/skills/skillssh?q=&limit= skills.sh رجسٹری میں تلاش کریں
POST /api/skills/skillssh/install skills.sh سے id کے ذریعے مہارت نصب کریں

توثیق: انتظامی session/API key۔ Marketplace تلاش کے routes انتظامی توثیق یا Bearer API key (isAuthenticated) میں سے کسی ایک کو قبول کرتے ہیں۔


میموری

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

طریقہ راستہ وضاحت
GET /api/memory میموریز کی فہرست — ?apiKeyId=, ?type=, ?sessionId=, ?q=، نیز offset/limit یا page/limit پیجینیشن
POST /api/memory میموری بنائیں — باڈی کی Zod کے ذریعے توثیق کی جاتی ہے: {content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}
GET /api/memory/[id] ایک میموری حاصل کریں
DELETE /api/memory/[id] ایک میموری حذف کریں
GET /api/memory/health میموری ذیلی نظام کی صحت (DB کنیکٹیویٹی، embeddings بیک اینڈ، vector index کی حالت)

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


MCP سرور

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

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

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


A2A سرور

OmniRoute معائنے/ڈیش بورڈ کے استعمال کے لیے REST ریپر کے ساتھ ایک A2A (Agent-to-Agent) JSON-RPC 2.0 اینڈ پوائنٹ فراہم کرتا ہے۔

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": "اس کوڈنگ کام کو روٹ کریں"}]
  }
}

معاونت یافتہ میتھڈز (سبھی settings.a2aEnabled کے تابع ہیں):

میتھڈ تفصیل
message/send ہم وقت مہارت کا نفاذ؛ {task, artifacts, metadata} واپس کرتا ہے
message/stream اسی مہارت کے مجموعے کا اسٹریمنگ SSE نفاذ
tasks/get taskId کے ذریعے کوئی ٹاسک حاصل کریں
tasks/cancel taskId کے ذریعے کوئی ٹاسک منسوخ کریں

بلٹ اِن مہارتیں: smart-routing، quota-management، provider-discovery، cost-analysis، health-report۔

ایجنٹ کارڈ

GET /.well-known/agent.json

عوامی A2A ایجنٹ کارڈ (نام، تفصیل، صلاحیتیں، مہارتوں کا کیٹلاگ، توثیقی اسکیم) واپس کرتا ہے — عوامی طور پر 1h کے لیے کیش کیا جاتا ہے۔ توثیق درکار نہیں۔

REST معاونین

میتھڈ پاتھ تفصیل
GET /api/a2a/status A2A فعال ہونے کی حالت + ٹاسک کے اعدادوشمار + کیش شدہ ایجنٹ کارڈ کا خلاصہ
GET /api/a2a/tasks ٹاسکس کی فہرست — ?state=submitted|working|completed|failed|cancelled، ?skill=، ?limit= (≤200)، ?offset=
POST /api/a2a/tasks (REST معاون کے طور پر نافذ نہیں کیا گیا — JSON-RPC message/send کے ذریعے بنائیں)
GET /api/a2a/tasks/[id] ایک ٹاسک بازیافت کریں
POST /api/a2a/tasks/[id]/cancel ایک ٹاسک منسوخ کریں

توثیق: REST معاونین انتظامی توثیق کے بغیر چلتے ہیں (ڈیش بورڈ سے قابلِ مطالعہ)؛ اگر ترتیب دیا گیا ہو تو JSON-RPC /a2a روٹ Bearer OMNIROUTE_API_KEY استعمال کرتا ہے۔


کلاؤڈ، Evals اور Assess

| طریقہ | راستہ | تفصیل | | ------ | ------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------- | ----------------------------------- | | POST | /api/cloud/auth | بیئرر کلید کی توثیق کریں اور کلاؤڈ سنک کلائنٹس کے لیے مخفی فراہم کنندہ کنکشنز + ماڈل عرف واپس کریں | | POST | /api/cloud/credentials/update | کلاؤڈ سے ہم وقت فراہم کنندہ کی خفیہ کردہ اسناد اپ ڈیٹ کریں | | POST | /api/cloud/model/resolve | مقامی روٹنگ ٹیبل استعمال کرتے ہوئے ایک منطقی ماڈل id کو کسی ٹھوس فراہم کنندہ/ماڈل سے حل کریں | | GET | /api/cloud/models/alias | کلاؤڈ سنک کے لیے ظاہر کیے گئے ماڈل عرف کی فہرست دکھائیں | | GET | /api/assess | تازہ ترین اسیسمنٹ زمرہ بندیاں پڑھیں (فی فراہم کنندہ/ماڈل) | | POST | /api/assess | ایک اسیسمنٹ چلائیں — باڈی: {scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?} | | GET | /api/evals | بلٹ اِن eval سویٹس + تازہ ترین رنز کی فہرست دکھائیں | | POST | /api/evals | ایک eval رن شروع کریں | | POST | /api/evals/suites | ایک حسبِ ضرورت eval سویٹ بنائیں — باڈی کی توثیق evalSuiteSaveSchema کے ذریعے کی جاتی ہے | | GET | /api/evals/suites/[id] | ایک حسبِ ضرورت eval سویٹ بازیافت کریں |

توثیق: /api/cloud/auth براہِ راست بیئرر کلید کی توثیق کرتا ہے اور صرف manage / admin اسکوپ والی کلید کے لیے ہر کنکشن کی مخفی کلید اور projectId واپس کرتا ہے؛ دیگر /api/cloud/*، /api/evals/*، اور /api/assess روٹس کے لیے مینجمنٹ سیشن/API کلید درکار ہوتی ہے۔ /api/assess POST ایک امتیازی-یونین اسکوپ اسکیما کے ساتھ 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 وقت کی مدت کے مطابق اعداد و شمار (طے شدہ 24h)

جواب کی مثال:

{
  "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 Shannon entropy پر مبنی تنوع کی ٹریکنگ: پرووائیڈر کے پھیلاؤ کی پیمائش کرکے ناکامی کے واحد نقاط کو روکتی ہے

جواب کی مثال:

{
  "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 کلید درکار ہے۔


کیش مینجمنٹ

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

طریقہ پاتھ وضاحت
GET /api/cache کیش کا جائزہ: کل اندراجات، ہِٹ ریٹ، ڈسک پر حجم
GET /api/cache/entries کیش شدہ اندراجات کی فہرست (صفحہ بندی کے ساتھ)
DELETE /api/cache/entries کیش اندراجات حذف کریں (کوئری پیرامیٹرز کے ذریعے فلٹر کریں)
GET /api/cache/stats کیش کے تفصیلی اعداد و شمار (فی پرووائیڈر، فی ماڈل)
GET /api/cache/reasoning ریزننگ کیش کی حالت (ریزننگ ری پلے کے لیے)
DELETE /api/cache/reasoning ریزننگ کیش صاف کریں — کوئری پیرامیٹرز: ?toolCallId=<id> (واحد) یا ?provider=<p> یا کوئی پیرامیٹر نہیں (تمام)

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


میموری سسٹم

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

طریقہ پاتھ وضاحت
GET /api/memory میموری اندراجات کی فہرست (دائرۂ کار، قسم، تلاش کی کوئری کے لحاظ سے فلٹر کریں)
POST /api/memory نیا میموری اندراج بنائیں — باڈی: {scope, type, content, metadata?}
GET /api/memory/[id] مخصوص میموری اندراج حاصل کریں
PUT /api/memory/[id] میموری اندراج اپ ڈیٹ کریں
DELETE /api/memory/[id] میموری اندراج حذف کریں
GET /api/memory?q= میموری میں تلاش کریں (FTS5 + ویکٹر) — اعداد و شمار اسی رسپانس میں شامل ہوتے ہیں

توثیق: مینجمنٹ سیشن یا مینجمنٹ دائرۂ کار والی API کلید درکار ہے۔


ویب ہُکس

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

طریقہ پاتھ وضاحت
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 ویب ہُک کو آزمائشی ایونٹ بھیجیں

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

ایونٹس کی تمام اقسام کے لیے ویب ہُکس فریم ورک دیکھیں۔


اسکلز فریم ورک

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

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

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

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


پلگ اِنز

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

طریقہ پاتھ تفصیل
GET /api/plugins انسٹال شدہ پلگ اِنز کی فہرست دکھائیں
POST /api/plugins/marketplace/install مارکیٹ پلیس سے ایک پلگ اِن انسٹال کریں
DELETE /api/plugins/[name] ایک پلگ اِن اَن انسٹال کریں
POST /api/plugins/[name]/activate ایک پلگ اِن فعال کریں
POST /api/plugins/[name]/deactivate ایک پلگ اِن غیر فعال کریں
GET /api/plugins/[name]/config پلگ اِن کی کنفیگریشن حاصل کریں
PUT /api/plugins/[name]/config پلگ اِن کی کنفیگریشن اپ ڈیٹ کریں

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

مکمل تفصیلات کے لیے پلگ اِنز فریم ورک دیکھیں۔


شیڈو راؤٹنگ

فراہم کنندگان کا شیڈو / A-B موازنہ ایک علیحدہ REST سطح نہیں ہے — اسے کومبو راؤٹنگ کے ذریعے کنفیگر کیا جاتا ہے (آٹو-کومبو دیکھیں)۔ ہر کومبو کے موازنے کے میٹرکس GET /api/combos/metrics کے ذریعے فراہم کیے جاتے ہیں۔


حفاظتی حدود

رن ٹائم حفاظتی حدود (PII کی شناخت، پرامپٹ انجیکشن کی شناخت، وژن برجنگ) کا معائنہ کریں۔ حفاظتی حدود ہر درخواست پر چلتی ہیں؛ ہر کال کے لیے آپٹ آؤٹ x-omniroute-disabled-guardrails درخواست ہیڈر کے ذریعے کیا جاتا ہے — فعال/غیر فعال کرنے کے لیے کوئی مستقل سطح موجود نہیں ہے۔

طریقہ پاتھ تفصیل
GET /api/guardrails رجسٹرڈ حفاظتی حدود اور ان کی حیثیت کی فہرست دکھائیں (نام / فعال / ترجیح)
POST /api/guardrails/test نمونہ ان پٹ پر پری کال پائپ لائن کا ڈرائی رَن کریں — باڈی: {input, disabledGuardrails?}

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

مکمل تفصیلات کے لیے سیکیورٹی > حفاظتی حدود دیکھیں۔



توثیق

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

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

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