mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-18 04:42:30 +03:00

Files

Diego Rodrigues de Sa e Souza b637350680 fix(docs): re-sync the 65 documentation mirror sets; section-level docs pipeline; drift gate blocking (#13940 )

1,104 mirrors rewritten over five passes of run-translation on the 22-source core set: the 14 sources edited since their translation, the 322 mirrors that were still English copies, and the frontmatter the old extractor leaked into the newer locales' bodies. The pipeline now caches per-`## `-section hashes and retranslates only changed sections, never reuses a section that is still English, rebuilds English-copy / leaked mirrors even when the source is unchanged, merges the state on save (parallel runs), and the drift gate (scoped to the core set) is blocking. Final audit: 0 stale, 0 English copies, 0 leaked frontmatter across 1,430 core mirrors.

⚠️ base-red inherited: #12732

2026-09-17 02:55:31 -03:00

146 KiB

Raw Blame History

API Reference (اردو)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇸🇦 ar · 🇦🇿 az · 🇧🇬 bg · 🇧🇩 bn · 🇨🇿 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

OmniRoute API کے لیے بنیادی حوالہ۔ اس میں عوامی /v1 سطح اور سب سے زیادہ استعمال ہونے والے انتظامی endpoints شامل ہیں؛ مشین کے ذریعے قابلِ مطالعہ docs/openapi.yaml اور src/app/api/ کے تحت موجود route tree جامع ذرائع ہیں۔

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

چیٹ تکمیلات
خصوصی منظم سیشن لیزز
ایمبیڈنگز
تصویر کی تخلیق
دستاویز OCR
ماڈلز کی فہرست
فراہم کنندہ پلگ اِن مینی فیسٹ
مطابقتی اینڈ پوائنٹس
فائلز API
بیچز API
تلاش API
WebSocket اسٹریمنگ
کوٹاز اور مسائل کی رپورٹنگ
سیمنٹک کیش
ڈیش بورڈ اور انتظام
کومبو انتظام
ویب ہُکس
رجسٹرڈ کلیدیں (خودکار انتظام)
ایجنٹس پروٹوکول
انتظامی پراکسیز
لچک پذیری (توسیع شدہ)
مہارتیں
میموری
MCP سرور
A2A سرور
کلاؤڈ، Evals اور Assess
درخواست کی پروسیسنگ
توثیق

چیٹ تکمیلات

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-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; فعال کریں۔

لاگت کی ٹیلی میٹری ہیڈرز: نان اسٹریمنگ کامیاب جوابات میں 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"}

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

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

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

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

{ "action": "status", "generation": 1 }

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

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

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

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

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

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

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

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

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

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

`x-omniroute-compression`

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

ویلیو	اثر
`off`	اس درخواست کے لیے کوئی کمپریشن نہیں۔
`default`	پینل سے اخذ کردہ Default پروفائل (فعال پروفائل کو نظر انداز کرتا ہے)۔
`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 فیملی: ایک اعلیٰ سطحی ارے، content.parts (text یا inline_data) کے ساتھ، ایک واحد مقامی models/{model}:embedContent درخواست بن جاتا ہے۔
واضح موڈیلٹی میٹا ڈیٹا کے بغیر نامعلوم/ڈائنامک ماڈلز ساختہ ان پٹ کو 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": "A beautiful sunset over mountains",
  "size": "1024x1024"
}

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

# تمام تصویری ماڈلز کی فہرست دکھائیں
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 فارمیٹ میں واپس کرتا ہے

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

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

GET /v1/models?prefix=alias        # فی ماڈل ایک آئی ڈی — مختصر عرفی سابقہ
GET /v1/models?prefix=dual         # دونوں صورتیں (سرور کا ڈیفالٹ)
GET /v1/models?prefix=canonical    # صرف مکمل provider-id سابقہ

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

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

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

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

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

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

اس آئی ڈی کو منتخب کرنے پر (مثلاً ایسی Claude Code کنفیگریشن میں جو ہمیشہ thinking بلاک منسلک کرتی ہے) یہ استدلال کو دبائے رکھتے ہوئے اصل <provider>/<model> پر واپس resolve ہو جاتی ہے — /v1/messages پاتھ پر thinking:{type:"disabled"}، یا /v1/chat/completions پاتھ پر reasoning/reasoning_effort فیلڈز کو حذف کر دیا جاتا ہے۔ یہ قسم صرف Claude فیملی کے ان ماڈلز کے لیے درج ہوتی ہے جو سوچنے کی صلاحیت کی معاونت کرتے اور 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 (STT)
POST	`/v1/audio/speech`	OpenAI TTS (آڈیو باڈی واپس کرتا ہے)
POST	`/v1/rerank`	Cohere/Voyage طرز کی ری رینکنگ
POST	`/v1/classify`	Jina درجہ بندی (`api.jina.ai`)
POST	`/v1/segment`	Jina سیگمینٹر (`segment.jina.ai`)
POST	`/v1/moderations`	OpenAI Moderations
GET	`/v1/models`	OpenAI
POST	`/v1/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 کیز بھی قبول کرتا ہے، خواہ کوئری اسٹرنگ مطابقت (?token=...، ?apiKey=...، ?api_key=...، ?key=...) کے ذریعے یا ذیل میں دستاویز کردہ مخصوص /api/v1/vscode/{token}/... اینڈ پوائنٹس کے ذریعے۔

# دوبارہ درجہ بندی
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" }

# تصویر میں ترمیم (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

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

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

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`	ہر فراہم کنندہ کے ہٹ/تاخیر/کیش کے اعدادوشمار

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

ویب بازیافت API

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

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

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

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

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 کلید اپنے استعمال اور کوٹاز کو پڑھ سکتی ہے—انتظامی تصدیق کی ضرورت نہیں۔ یہ وہ endpoint ہے جسے کلائنٹ (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 مینیجر اسے ہر کلید کے لیے الگ سے ٹوگل کرتا ہے)۔ اس کے بغیر endpoint کا جواب 403 ہوتا ہے۔

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

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

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

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

سیمنٹک کیش

# کیش کے اعداد و شمار حاصل کریں
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 کی مثالیں: نظم و نسق کی توثیق۔

توثیق

اینڈ پوائنٹ	طریقہ	تفصیل
`/api/auth/login`	POST	لاگ اِن
`/api/auth/logout`	POST	لاگ آؤٹ
`/api/settings/require-login`	GET/PUT	لاگ اِن کی شرط کو فعال یا غیر فعال کریں

فراہم کنندہ کا نظم و نسق

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

OAuth کے بہاؤ

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

روٹنگ اور config

اینڈ پوائنٹ	طریقہ	تفصیل
`/api/models/alias`	GET/POST	ماڈل کے متبادل نام
`/api/models/catalog`	GET	فراہم کنندہ + قسم کے لحاظ سے تمام ماڈلز
`/api/combos*`	مختلف	combo کا نظم و نسق
`/api/keys*`	مختلف	API key کا نظم و نسق
`/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/settings`	GET/PUT/PATCH	عمومی ترتیبات
`/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	انتظامی توثیق/پروب سے پہلے قابلِ اعتماد لوپ بیک کی سخت جانچ؛ صاف شدہ FFmpeg/ffprobe دستیابی اور ورژنز (no-store)
`/api/modality-bridge/video/extract`	POST	داخلی، توثیق شدہ، قابلِ اعتماد لوپ بیک بائٹ بروکر؛ 50 MiB ان پٹ، محدود قطار/32 MiB آؤٹ پٹ، `503` گنجائش، `499` منقطع ہونا، `504` آخری مہلت؛ یہ عوامی اپ لوڈ API نہیں ہے

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

اینڈ پوائنٹ	طریقہ	تفصیل
`/api/db-backups`	GET	دستیاب بیک اپس کی فہرست
`/api/db-backups`	PUT	دستی بیک اپ بنائیں
`/api/db-backups`	POST	کسی مخصوص بیک اپ سے بحال کریں
`/api/db-backups/export`	GET	ڈیٹابیس کو .sqlite فائل کے طور پر ڈاؤن لوڈ کریں
`/api/db-backups/import`	POST	ڈیٹابیس تبدیل کرنے کے لیے .sqlite فائل اپ لوڈ کریں
`/api/db-backups/exportAll`	GET	مکمل بیک اپ کو .tar.gz آرکائیو کے طور پر ڈاؤن لوڈ کریں

کلاؤڈ سنک

اینڈ پوائنٹ	طریقہ	تفصیل
`/api/sync/cloud`	مختلف	کلاؤڈ سنک کی کارروائیاں
`/api/sync/initialize`	POST	سنک کو شروع کریں
`/api/cloud/*`	مختلف	کلاؤڈ کا نظم و نسق

ٹنلز

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

CLI ٹولز

اینڈ پوائنٹ	طریقہ	تفصیل
`/api/cli-tools/claude-settings`	GET	Claude CLI کی حالت
`/api/cli-tools/codex-settings`	GET	Codex CLI کی حالت
`/api/cli-tools/droid-settings`	GET	Droid CLI کی حالت
`/api/cli-tools/openclaw-settings`	GET	OpenClaw CLI کی حالت
`/api/cli-tools/runtime/[toolId]`	GET	عمومی CLI رن ٹائم

CLI جوابات میں یہ شامل ہیں: installed، runnable، command، commandPath، runtimeMode، reason۔

ACP ایجنٹس

اینڈ پوائنٹ	طریقہ	تفصیل
`/api/acp/agents`	GET	حالت کے ساتھ تمام شناخت شدہ ایجنٹس (بلٹ اِن + حسبِ ضرورت) کی فہرست
`/api/acp/agents`	POST	حسبِ ضرورت ایجنٹ شامل کریں یا شناختی کیش ریفریش کریں
`/api/acp/agents`	DELETE	`id` کوئری پیرامیٹر کے ذریعے حسبِ ضرورت ایجنٹ ہٹائیں

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

بحالی کی صلاحیت اور شرح کی حدود

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

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

جائزے

اینڈ پوائنٹ	طریقہ	تفصیل
`/api/evals`	GET/POST	جائزہ سویٹس کی فہرست / جائزہ چلائیں

پالیسیاں

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

تعمیل

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

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

اینڈ پوائنٹ	طریقہ	تفصیل
`/v1beta/models`	GET	Gemini فارمیٹ میں ماڈلز کی فہرست
`/v1beta/models/{...path}`	POST	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 فراہم کنندہ کے ماحولیاتی متغیرات کی مرمت کرنا

نوٹ: یہ اینڈ پوائنٹس سسٹم کے اندرونی استعمال یا 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"
}

آڈیو ٹرانسکرپشن

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

کسی بھی تشکیل کردہ STT فراہم کنندہ کے ذریعے آڈیو فائلوں کو تحریر میں تبدیل کریں۔ پہلا پاتھ سیگمنٹ مقامی فراہم کنندہ کو منتخب کرتا ہے (openai/…، deepgram/…)۔ وہ گیٹ ویز جو کسی دوسرے وینڈر کے ماڈل کو دوبارہ برآمد کرتے ہیں، ایک مکمل شناخت استعمال کرتے ہیں (openrouter/deepgram/nova-3)۔

درخواست:

curl -X POST http://localhost:20128/v1/audio/transcriptions \
  -H "Authorization: Bearer your-api-key" \
  -F "file=@recording.mp3" \
  -F "model=openai/whisper-1"

جواب:

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

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

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

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 پائپ لائن کے ذریعے نافذ کی جاتی ہے)۔

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

کلائنٹ /v1/* کو درخواست بھیجتا ہے
روٹ ہینڈلر handleChat، handleEmbedding، handleAudioTranscription، یا handleImageGeneration کو کال کرتا ہے
ماڈل متعین کیا جاتا ہے (براہِ راست provider/model یا alias/combo)
اکاؤنٹ کی دستیابی کی فلٹرنگ کے ساتھ مقامی DB سے اسناد منتخب کی جاتی ہیں
چیٹ کے لیے: handleChatCore semantic/signature کیش کی جانچ کرتا ہے اور combo کمپریشن کی ترتیبات متعین کرتا ہے
فعال ہونے کی صورت میں، provider ترجمے سے پہلے پیشگی کمپریشن چلتی ہے (lite، Caveman، RTK، یا stacked)
Provider executor upstream درخواست بھیجتا ہے
جواب کو واپس کلائنٹ فارمیٹ میں ترجمہ کیا جاتا ہے (چیٹ)، یا جوں کا توں واپس کیا جاتا ہے (embeddings/images/audio)
استعمال، کمپریشن analytics، اور درخواست کے لاگز ریکارڈ کیے جاتے ہیں
خرابیوں کی صورت میں 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 جیسا ہی اثر)

تصدیق: Bearer API کلید (isAuthenticated)۔ /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`	Bearer کلید کی تصدیق کریں اور کلاؤڈ سنک کلائنٹس کے لیے مخفی کردہ پرووائیڈر کنکشنز + ماڈل عرف واپس کریں
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 براہِ راست Bearer کلید کی توثیق کرتا ہے؛ دیگر /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، chipotle، 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) دیکھیں۔

146 KiB Raw Blame History Unescape Escape

API Reference (اردو)

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

چیٹ تکمیلات

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

خصوصی مینیجڈ سیشن لیزز

x-omniroute-compression

ایمبیڈنگز

تصویر بنانا

دستاویز OCR

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

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

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

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

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

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

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

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

Files API

Batches API

تلاش API

ویب بازیافت API

WebSocket اسٹریمنگ

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

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

OpenAI Codex CLI کی ترتیب

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

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

سیمنٹک کیش

تاخیر پر اثر

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

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

ڈیش بورڈ اور نظم و نسق

توثیق

فراہم کنندہ کا نظم و نسق

OAuth کے بہاؤ

روٹنگ اور config

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

ترتیبات

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

نگرانی

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

کلاؤڈ سنک

ٹنلز

CLI ٹولز

ACP ایجنٹس

بحالی کی صلاحیت اور شرح کی حدود

جائزے

پالیسیاں

تعمیل

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

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

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

آڈیو ٹرانسکرپشن

Ollama مطابقت

ٹوکنائزڈ VS Code / ہیڈر کے بغیر متبادل راستے

ٹیلی میٹری

بجٹ

ٹوکن کی حدود

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

Combo کا انتظام

ویب ہُکس

رجسٹرڈ کلیدیں (خودکار انتظام)

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

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

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

مہارتیں

میموری

MCP سرور

A2A سرور

JSON-RPC

ایجنٹ کارڈ

REST معاونین

کلاؤڈ، Evals اور Assess

ACP (Agent Client Protocol) کا انتظام

تجزیات اور مشاہدہ پذیری

خودکار راؤٹنگ کے تجزیات

کمپریشن کے تجزیات

پرووائیڈر کے تنوع کی ٹریکنگ

ایڈمن آپریشنز

146 KiB

Raw Blame History

`x-omniroute-compression`

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

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

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