mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-18 12:52:25 +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

145 KiB

Raw Blame History

API Reference (العربية)

🌐 Languages: 🇺🇸 English · 🇪🇹 am · 🇦🇿 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 · 🇵🇰 ur · 🇺🇿 uz · 🇻🇳 vi · 🇳🇬 yo · 🇨🇳 zh-CN · 🇹🇼 zh-TW

المرجع الأساسي لواجهة OmniRoute API. يغطي واجهة /v1 العامة ونقاط نهاية الإدارة الأكثر استخدامًا؛ ويُعد كل من ملف docs/openapi.yaml القابل للقراءة آليًا وشجرة المسارات ضمن src/app/api/ المصدرين الشاملين.

جدول المحتويات

إكمالات الدردشة
عقود إيجار حصرية للجلسات المُدارة
التضمينات
توليد الصور
التعرّف الضوئي على المستندات
سرد النماذج
بيان إضافة المزوّد
نقاط نهاية التوافق
واجهة برمجة تطبيقات الملفات
واجهة برمجة تطبيقات الدُفعات
واجهة برمجة تطبيقات البحث
البث عبر WebSocket
الحصص والإبلاغ عن المشكلات
ذاكرة التخزين المؤقت الدلالية
لوحة المعلومات والإدارة
إدارة المجموعات
خطافات الويب
المفاتيح المسجّلة (الإدارة التلقائية)
بروتوكول الوكلاء
وكلاء الإدارة
المرونة (موسّعة)
المهارات
الذاكرة
خادم MCP
خادم A2A
السحابة والتقييمات والتقدير
معالجة الطلبات
المصادقة

إكمالات الدردشة

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

{
  "model": "cc/claude-opus-4-6",
  "messages": [
    {"role": "user", "content": "اكتب دالةً من أجل..."}
  ],
  "stream": true
}

الرؤوس المخصّصة

الرأس	الاتجاه	الوصف
`X-OmniRoute-No-Cache`	الطلب	اضبطه على `true` لتجاوز ذاكرة التخزين المؤقت
`x-omniroute-no-memory`	الطلب	اضبطه على `true` لتخطي حقن الذاكرة والمهارات لهذا الطلب (يماثل عدم استخدام ذاكرة التخزين المؤقت، ويتجنب تكلفة الرموز/التكلفة لكل استدعاء)
`X-OmniRoute-Progress`	الطلب	اضبطه على `true` للحصول على أحداث التقدم
`X-Session-Id`	الطلب	مفتاح جلسة ثابت لتقارب الجلسات الخارجية
`x_session_id`	الطلب	يُقبل أيضًا الشكل ذو الشرطة السفلية (عبر HTTP مباشرةً)
`X-OmniRoute-Session-Id`	الطلب	وسم للجلسة/المحادثة يقدّمه المستدعي (ويغذي الذاكرة أيضًا). عند وجوده، يُحفظ حرفيًا في `call_logs.session_tag` لإسناد التكلفة لكل جلسة (#8249) — ولا يُنشأ مطلقًا عند غيابه
`Idempotency-Key`	الطلب	مفتاح إزالة التكرار (نافذة مدتها 5 ثوانٍ)
`X-Request-Id`	الطلب	مفتاح بديل لإزالة التكرار
`X-OmniRoute-Cache`	الاستجابة	`HIT` أو `MISS` (دون بث)
`X-OmniRoute-Idempotent`	الاستجابة	`true` إذا أُزيل التكرار
`X-OmniRoute-Progress`	الاستجابة	`enabled` إذا كان تتبع التقدم مفعّلًا
`X-OmniRoute-Session-Id`	الاستجابة	معرّف الجلسة الفعلي الذي تستخدمه OmniRoute
`X-OmniRoute-Request-Id`	الاستجابة	معرّف ربط الطلب (عندما يكون معروفًا)
`X-OmniRoute-Version`	الاستجابة	إصدار بناء OmniRoute (موجود دائمًا)
`X-OmniRoute-Cost-Saved`	الاستجابة	المبلغ بالدولار الأمريكي الذي وفّرته ذاكرة التخزين المؤقت عند حدوث `HIT` (لإصابات ذاكرة التخزين المؤقت فقط)
`X-OmniRoute-Decision`	الاستجابة	تتبّع التوجيه: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` هو استراتيجية المجموعة، أو `single` لطلب غير مجمّع) — موجود دائمًا في استجابات الاكتمال

ملاحظة حول Nginx: إذا كنت تعتمد على الرؤوس التي تحتوي على شرطات سفلية (مثل x_session_id)، ففعّل underscores_in_headers on;.

ترويسات قياس التكلفة: تحمل استجابات النجاح غير المتدفقة أيضًا مجموعة قياس التكلفة X-OmniRoute-* — وهي X-OmniRoute-Response-Cost (بالدولار الأمريكي، مع 10 منازل عشرية ثابتة؛ 0.0000000000 للخدمات المجانية/غير المسعّرة)، وX-OmniRoute-Tokens-In / X-OmniRoute-Tokens-Out، وX-OmniRoute-Model، وX-OmniRoute-Provider، وX-OmniRoute-Latency-Ms، وX-OmniRoute-Cache-Hit، وX-OmniRoute-Fallback-Attempts (فقط عندما تكون > 0)، بالإضافة إلى X-OmniRoute-Request-Id وX-OmniRoute-Version. تُصدر هذه الترويسات بواسطة إكمالات المحادثة، و/v1/responses، و/v1/messages، وكذلك نقاط نهاية الوسائط — وهي /v1/embeddings، و/v1/images/generations، و/v1/audio/speech، و/v1/audio/transcriptions، و/v1/rerank، و/v1/videos/generations، و/v1/music/generations، و/v1/moderations (بتكلفة 0 دائمًا). تُحسب تكلفة الوسائط لكل نمط (لكل صورة، أو لكل ثانية، أو لكل محرف، أو لكل وحدة بحث) عند توفر التسعير، وإلا فتكون 0 (السماح بالمتابعة عند التعذر).

دلالات تكلفة إصابة ذاكرة التخزين المؤقت: عند حدوث إصابة في ذاكرة التخزين المؤقت الدلالية (X-OmniRoute-Cache-Hit: true)، لا يُجرى أي استدعاء للجهة المنفذة، ولذلك تكون قيمة X-OmniRoute-Response-Cost هي 0.0000000000 (التكلفة الإضافية لخدمة الإصابة). تُبلَّغ التكلفة الأصلية/التي كان من الممكن تكبدها بشكل منفصل في X-OmniRoute-Cost-Saved. ينبغي لمستهلكي بيانات الفوترة جمع قيم X-OmniRoute-Response-Cost (فالإصابات لا تكلّف شيئًا)؛ ويمكن لتحليلات ذاكرة التخزين المؤقت تجميع قيم X-OmniRoute-Cost-Saved.

عقود الإيجار الحصرية للجلسات المُدارة

يُعد تأجير الجلسات المُدارة حصريًا عقد توجيه اختياريًا ومحايدًا تجاه العميل: يحتفظ مالك نشط واحد باتصال OmniRoute واحد مؤهل. ولا يؤجّر نموذجًا، أو يتطلب OAuth، أو يحدد عميلًا بعينه، أو يتطلب مزودًا بعينه.

يجب أن يحتوي مفتاح API المستخدم للمصادقة على النطاق lease:exclusive وقائمة صريحة غير فارغة من allowedConnections. ويفرض حدّ تعديل قاعدة البيانات وجود كلا الحقلين معًا عند إنشاء المفتاح وإجراء التحديثات الجزئية.

POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-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 من دون بيانات وصفية للاتصال. لا يملك العميل الذي تلقى استجابة انتظار السعة أي ارتباط نشط لفحصه. عندما ينقل التوجيه عقد إيجار نشطًا، يظل الجيل نفسه صالحًا، وتُرجع الحالة الارتباط الجديد ذريًا، لا القديم مطلقًا. تظل التطبيقات العميلة الحالية من دون تغيير لأن استجابات الاستحواذ والتجديد والتحرير والانتظار تحتفظ ببُناها السابقة.

لا يغيّر عقد الخادم هذا /status القياسي في OpenAI Codex. يُبلغ 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`	الملف الشخصي الافتراضي المستمد من اللوحة (يتجاهل الملف الشخصي النشط).
`engine:<id>`	محرك واحد عندما يكون مفعّلًا، مثل `engine:rtk`.
`<combo>`	مجموعة مسماة، تُطابق بالاسم أولًا (من دون حساسية لحالة الأحرف)، ثم بالمعرّف.

ملاحظات:

تُتجاهل القيم غير المعروفة (لا يُرفض الطلب مطلقًا)؛ وينتقل الحل إلى أسبقية عوامل التشغيل العادية.
إذا كانت عدة مجموعات تشترك في الاسم نفسه، فمرّر id المجموعة للحصول على تطابق حتمي.
لا يمكن تحديد مجموعة اسمها off أو default بالاسم (إذ تُفسر هاتان الكلمتان المفتاحيتان أولًا)؛ فارجع إلى مثل هذه المجموعة باستخدام المعرّف الخاص بها.
مفتاح الضغط الرئيسي هو بوابة صارمة: عندما يكون الضغط معطلًا عموميًا، لا يمكن لهذه الترويسة تفعيله.

تُعاد الخطة المطبقة في ترويسة الاستجابة:

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

حيث تكون <source> إحدى القيم request-header أو routing-override أو active-profile أو auto-trigger أو default أو off.

التضمينات

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

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

المزوّدون المتاحون: Nebius وOpenAI وMistral وTogether AI وFireworks وNVIDIA وOpenRouter وJina AI.

تكون معرّفات الكتالوج بالصيغة provider/model (مثال: jina-ai/jina-embeddings-v5-omni-small). كما يمكن استخدام معرّفات نماذج Jina المجرّدة التي تظهر في السجل (مثل jina-embeddings-v5-text-small وjina-reranker-v3.5). تستخدم عمليات التضمين/إعادة الترتيب/التصنيف/التقسيم في Jina بيانات اعتماد لوحة التحكم jina-ai أولًا؛ ولا يُستخدم JINA_AI_API_KEY كخيار احتياطي إلا في حال عدم وجود مفتاح في لوحة التحكم. بطاقة jina-reader مخصّصة فقط لـ Reader / r.jina.ai‏ (POST /v1/web/fetch)، ولا توفّر أبدًا خدمات التضمين أو إعادة الترتيب.

تقبل نماذج السجل التي تعلن دعمها للوسائط المتعددة أيضًا ما يصل إلى 32 عنصرًا منظّمًا ومحايدًا بالنسبة إلى المزوّد. أنواع عناصر الوسائط هي text وimage وaudio وvideo وdocument. ويكون source للوسائط إما {"type":"url","url":"https://..."} أو {"type":"base64","data":"...","media_type":"..."}.

يقبل Jina v5 Omni ‏(jina-ai/jina-embeddings-v5-omni-small وjina-ai/jina-embeddings-v5-omni-nano والاسم المستعار للعائلة jina-ai/jina-embeddings-v5-omni → omni-small) أيضًا مستندات EmbeddingsV5Request الأصلية من Jina، ويمرّرها كما هي إلى https://api.jina.ai/v1/embeddings:

{
  "model": "jina-ai/jina-embeddings-v5-omni-small",
  "task": "retrieval.query",
  "normalized": true,
  "input": [
    { "text": "a red bicycle" },
    { "image": "https://example.com/bike.png" },
    {
      "content": [{ "text": "caption" }, { "image": "data:image/png;base64,..." }]
    }
  ]
}

يمكن أن تكون قيم { image | audio | video | pdf } الأصلية عنوان URL عامًا يستخدم HTTPS، أو URI من نوع data:، أو بيانات base64 خام. لا يحوّل OmniRoute هذه الكائنات إلى سلاسل نصية ولا يجلب عناوين URL الأصلية للصور — بل تسترجع Jina الوسائط العامة بنفسها. تُمرَّر حقول Jina الإضافية (task وnormalized وtruncate وembedding_type). وتظل وحدات SKU النصية فقط من Jina ترفض المستندات غير النصية.

حدود الأمان والنقل:

يجب أن تكون عناوين URL للوسائط البعيدة عامة وتستخدم HTTPS. تُجلب عناصر {type,source:url} القياسية من جهة الخادم (مع إعادة التحقق من عمليات إعادة التوجيه، والمهلة الزمنية، وحدود الحجم، ونظام DNS العام، وتثبيت الاتصال)، ثم تُضمَّن قبل استدعاء المزوّد. أما عناصر Jina الأصلية من نوع {image:"https://..."} فتُمرَّر كما هي بعد إجراء فحص HTTPS العام نفسه؛ وتتولى Jina جلب عنوان URL.
يقتصر حجم وسائط base64 المضمّنة على 8 MiB بعد فك الترميز لكل عنصر، وعلى 16 MiB بعد فك الترميز لإجمالي الطلب.

التحويل الخاص بالمزوّد (لا تُمرَّر العناصر القياسية مطلقًا دون تغيير):

نماذج Jina متعددة الوسائط: يتحول كل عنصر من المستوى الأعلى إلى كائن واحد ذي مفتاح خاص بنمط الوسائط (text / image / audio / video / pdf) باستخدام معرّفات URI من نوع data للوسائط المضمّنة؛ ومتجه واحد لكل عنصر من المستوى الأعلى.
عائلة Gemini Embedding 2: تتحول مصفوفة واحدة من المستوى الأعلى إلى طلب أصلي واحد من نوع models/{model}:embedContent مع content.parts ‏(text أو inline_data).
ترفض النماذج غير المعروفة/الديناميكية التي لا تحتوي على بيانات وصفية صريحة لنمط الوسائط الإدخال المنظّم باستخدام 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، وSD WebUI (محلي)، وComfyUI (محلي).

# عرض جميع نماذج الصور
GET /v1/images/generations

التعرّف الضوئي على الأحرف في المستندات

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

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

يحدّد model مزوّد OCR عبر بادئة provider/model؛ ويُربط معرّف النموذج المجرّد (مثل mistral-ocr-latest) بمزوّده المسجّل، وعند حذف model يكون الإعداد الافتراضي هو Mistral (mistral-ocr-latest). المزوّدون المسجّلون (open-sse/config/ocrRegistry.ts):

معرّف المزوّد	معرّف النموذج	قيمة `model`	ملاحظات
`mistral`	`mistral-ocr-latest`	`mistral/mistral-ocr-latest` (أو `mistral-ocr-latest` مجرّدًا)	متزامن — تُعاد الاستجابة مباشرةً من استدعاء المصدر الوحيد.
`azure-document-intelligence`	`prebuilt-read`	`azure-document-intelligence/prebuilt-read`	مصدر غير متزامن (`analyze` + الاستقصاء) — انظر أدناه.
`vertex-deepseek-ocr`	`deepseek-ocr-maas`	`vertex-deepseek-ocr/deepseek-ocr-maas`	متزامن، عبر نقطة نهاية الشريك `openapi/chat/completions` في Vertex AI — انظر أدناه للمصادقة/عنوان URL.

يستجيب المزوّدون الثلاثة جميعًا بالنص نفسه ذي البنية المشابهة لبنية Mistral:

{
  "pages": [{ "index": 0, "markdown": "# النص المستخرج..." }],
  "model": "mistral-ocr-latest",
  "usage_info": { "pages_processed": 1 }
}

تدفّق الاستقصاء في Azure Document Intelligence

واجهة API المسماة analyze في Azure Document Intelligence غير متزامنة: يُعيد الطلب الأولي ترويسة Operation-Location بدلًا من نص استجابة، ويجب استقصاء النتيجة. يستقصي المعالج (open-sse/handlers/ocr.ts) عنوان URL ذلك كل ثانية لما يصل إلى 30 محاولة، ويفشل سريعًا (أي لا يواصل الاستقصاء) عند استجابة استقصاء ليست ok أو عند حالة "failed"، ويُعيد 504 إذا كانت العملية لا تزال قيد التشغيل بعد استنفاد عدد المحاولات. تُطبَّع استجابة Azure النهائية إلى بنية pages/markdown نفسها التي تستخدمها Mistral قبل إعادتها إلى المستدعي، ولذلك لا تحتاج شيفرة العميل إلى معالجة المزوّد كحالة خاصة.

مصادقة Vertex AI DeepSeek OCR وتحديد نقطة النهاية

يعيد vertex-deepseek-ocr استخدام مصادقة Vertex AI نفسها التي يدعمها OmniRoute بالفعل لحركة مرور المحادثات/الصور (open-sse/executors/vertex.ts): يكون مفتاح API الخاص بالاتصال إما بيانات اعتماد JSON لحساب خدمة (تُستبدل برمز وصول OAuth قصير الأجل عبر تدفّق JWT bearer) أو رمز وصول OAuth مُنشأ مسبقًا يُستخدم كما هو. عنوان URL لنقطة نهاية المصدر هو نقطة نهاية الشريك العامة openapi/chat/completions الخاصة بـ Vertex، ويُنشأ من مشروع الاتصال ومنطقته — تكون لقيمة providerSpecificData.project/providerSpecificData.region الصريحة الأولوية دائمًا؛ وإلا فيُستمد المشروع من project_id في JSON الخاص بحساب الخدمة، وتكون المنطقة الافتراضية us-central1. يحدث كلا التحديدين في open-sse/handlers/ocr.ts (resolveVertexOcrAccessToken، resolveVertexOcrBaseUrl)، وتستخدمهما src/app/api/v1/ocr/route.ts قبل تمرير الطلب إلى handleOcr.

سرد النماذج

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

→ يُرجع جميع نماذج المحادثة والتضمين والصور + التركيبات بتنسيق OpenAI

بادئات معرّفات النماذج (`?prefix=`)

تُعرض معظم النماذج تحت بادئة المزوّد. تُحدَّد البادئة التي تحصل عليها بواسطة علامة الميزة MODELS_CATALOG_PREFIX_MODE، ويمكن تجاوزها لكل طلب باستخدام معامل استعلام — وهذا مفيد للعميل الذي يريد قائمة مرتبة من دون تغيير الإعداد على مستوى الخادم لجميع المستخدمين الآخرين:

GET /v1/models?prefix=alias        # معرّف واحد لكل نموذج — بادئة الاسم المستعار القصيرة
GET /v1/models?prefix=dual         # كلا الشكلين (إعداد الخادم الافتراضي)
GET /v1/models?prefix=canonical    # بادئة معرّف المزوّد الكاملة فقط

الوضع	ما يُصدره	ملاحظات
`dual`	`cc/claude-sonnet-4-6` و `claude/claude-sonnet-4-6`	الافتراضي. يوجَّه كلا المعرّفين إلى النموذج نفسه؛ وقد أُبقيا لضمان استمرار عمل إعدادات العملاء التي ثبّتت أحد الشكلين. يؤدي ذلك إلى مضاعفة حجم الكتالوج تقريبًا.
`alias`	`cc/claude-sonnet-4-6`	إدخال واحد لكل نموذج. لا يزال المزوّدون الذين ليس لديهم اسم مستعار مميّز يُصدرون إدخالهم، لذلك لا يُفقد أي شيء.
`canonical`	`claude/claude-sonnet-4-6`	إدخال واحد لكل نموذج تحت بادئة معرّف المزوّد الكاملة. كما يُصدر المزوّدون الذين ليس لديهم اسم مستعار مميّز (مثل `antigravity/…` و`agy/…`) معرّفهم الوحيد هنا أيضًا، لذلك لا يُفقد أي شيء.

يمكن أيضًا التعرّف على النسخة المطابقة التي تعمل بوضع dual من دون معامل الاستعلام: إذ تتضمن حقل parent يشير إلى المعرّف الأساسي.

ينبغي للعملاء الذين يعرضون أداة لاختيار النماذج طلب ?prefix=alias — وهذا ما تفعله إضافة OmniCopilot لـ VS Code.

متغيرات النماذج من دون تفكير

بالنسبة إلى نماذج Claude القادرة على التفكير، تعرض /v1/models أيضًا متغيرًا من دون تفكير يبدأ معرّفه بالبادئة claude-3-omniroute-no-thinking/:

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

يؤدي تحديد هذا المعرّف (مثلًا في إعداد Claude Code يُرفق دائمًا كتلة thinking) إلى الرجوع إلى <provider>/<model> الفعلي مع تعطيل الاستدلال — باستخدام thinking:{type:"disabled"} في مسار /v1/messages، أو بإسقاط حقلي reasoning وreasoning_effort في مسار /v1/chat/completions. لا يُدرج هذا المتغير إلا لنماذج عائلة Claude التي تدعم التفكير وتحترم القيمة disabled (لذلك تُستبعد، مثلًا، النماذج التكيفية فقط التي ترفض disabled). يمكن للمشغّلين فرض تفعيل المتغير أو تعطيله لكل نموذج عبر ModelSpec.noThinkingAlias.

بيان إضافة المزوّد

GET /api/v1/provider-plugin-manifest

يعيد بيان إضافة المزوّد الآمن للاستخدام بصيغة JSON، والذي تستخدمه Bifrost وCLIProxyAPI وأجهزة التوجيه الجانبية المستقبلية. تُنشأ الاستجابة من سجل مزوّدي TypeScript، وتستبعد عمدًا أسرار عملاء OAuth، وحلّ بيئة وقت التشغيل، ودوال التنفيذ، وترويسات الطلبات، وبيانات الحسابات.

استخدم نقطة النهاية هذه عندما تعمل خدمة جانبية خارج العملية ولا يمكنها استيراد open-sse/config/providerPluginManifestRegistry.ts مباشرةً.

نقاط نهاية التوافق

الطريقة	المسار	التنسيق
POST	`/v1/chat/completions`	OpenAI
POST	`/v1/messages`	Anthropic
POST	`/v1/responses`	استجابات OpenAI
POST	`/v1/embeddings`	OpenAI
POST	`/v1/images/generations`	صور OpenAI
POST	`/v1/images/edits`	صور OpenAI (تحرير/ترميم)
POST	`/v1/videos/generations`	إنشاء فيديو بأسلوب OpenAI
POST	`/v1/music/generations`	إنشاء موسيقى بأسلوب OpenAI
POST	`/v1/audio/transcriptions`	صوت OpenAI (تحويل الكلام إلى نص)
POST	`/v1/audio/speech`	تحويل النص إلى كلام من OpenAI (يعيد محتوى صوتيًا)
POST	`/v1/rerank`	إعادة ترتيب بأسلوب Cohere/Voyage
POST	`/v1/classify`	تصنيف Jina ‏(`api.jina.ai`)
POST	`/v1/segment`	مُجزّئ Jina ‏(`segment.jina.ai`)
POST	`/v1/moderations`	الإشراف على المحتوى من OpenAI
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
POST	`/api/v1/vscode/{token}/api/chat`	اسم مستعار مُرمّز برمز لـ Ollama
GET	`/api/v1/vscode/{token}/api/tags`	اسم مستعار مُرمّز برمز لوسوم Ollama

تتبع جميع مسارات POST البنية نفسها: Bearer your-api-key + محتوى JSON تم التحقق منه باستخدام Zod ‏(v1RerankSchema وv1ModerationSchema وv1AudioSpeechSchema وغيرها؛ راجع src/shared/validation/schemas.ts). تُعاد حالة 4xx عند فشل التحقق من المخطط.

بالنسبة إلى العملاء الذين لا يمكنهم إرفاق Authorization: Bearer ...، يقبل OmniRoute أيضًا مفاتيح API ضمن عنوان URL، إما عبر توافق سلسلة الاستعلام (?token=... أو ?apiKey=... أو ?api_key=... أو ?key=...) أو عبر نقاط النهاية المخصصة /api/v1/vscode/{token}/... الموثقة أدناه.

# إعادة الترتيب
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": "..." }

# تحويل النص إلى كلام — يعيد محتوى audio/mpeg (أو التنسيق المطلوب)
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# تحرير صورة (متعدد الأجزاء)
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.

واجهة برمجة تطبيقات الملفات

نقطة نهاية متوافقة مع 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 من نوع Bearer — تُحدَّد نطاقات الملفات لكل مفتاح API عبر getApiKeyRequestScope. لا يمكن للمفتاح رؤية ملفاته وتنزيلها وحذفها إلا؛ بينما يمكن لجلسة لوحة المعلومات من دون مفتاح قراءة المثيل بأكمله؛ ويُحظر على كل مستدعٍ لا يستخدم جلسة الوصول إلى ملف بلا مالك (تحميل مجهول أو عبر جلسة لوحة المعلومات). يرفض GET /v1/files المستدعي المجهول — وكذلك المفتاح المقدَّم الذي يتعذر التحقق منه — باستخدام 401 حتى عندما تكون REQUIRE_API_KEY=false، بدلًا من سرد ملفات جميع المستأجرين (GHSA-m3hp-hq9g-fpmv، GHSA-2jm2-mpx8-6523).

واجهة برمجة تطبيقات الدفعات

معالجة دفعية متوافقة مع OpenAI.

الطريقة	المسار	الوصف
POST	`/v1/batches`	إنشاء دفعة — يتم التحقق من صحة النص الأساسي بواسطة `v1BatchCreateSchema` (`input_file_id`، `endpoint`، `completion_window`)
GET	`/v1/batches`	سرد الدفعات
GET	`/v1/batches/[id]`	استرداد حالة الدفعة + `request_counts`
DELETE	`/v1/batches/[id]`	حذف دفعة مكتملة/فاشلة
POST	`/v1/batches/[id]/cancel`	إلغاء دفعة قيد التنفيذ

المصادقة: مفتاح API من نوع Bearer. تُحدَّد نطاقات الدفعات لكل مفتاح API وفق القاعدة الثلاثية نفسها المطبقة على الملفات: مفتاحه الخاص فقط، وجلسة لوحة المعلومات على مستوى المثيل بالكامل، وتُحظر السجلات ذات المالك الفارغ على كل مستدعٍ لا يستخدم جلسة (الاسترداد والحذف والإلغاء، وكذلك التحقق من input_file_id عند الإنشاء). يرفض GET /v1/batches المستدعي المجهول باستخدام 401 حتى عندما تكون REQUIRE_API_KEY=false.

واجهة برمجة تطبيقات البحث

طبقة تجريد لموفّري بحث الويب (Tavily وBrave وExa وSerper وغيرها).

الطريقة	المسار	الوصف
GET	`/v1/search`	سرد موفّري البحث المهيّئين وإمكاناتهم
POST	`/v1/search`	تنفيذ استعلام بحث — يُتحقق من صحة المتن بواسطة `v1SearchSchema`، مع دعم التخزين المؤقت/الدمج
GET	`/v1/search/analytics`	إحصاءات النتائج/زمن الاستجابة/التخزين المؤقت لكل موفّر

المصادقة: مفتاح API بنمط Bearer (extractApiKey + isValidApiKey). تُفرض سياسة البحث عبر enforceApiKeyPolicy.

واجهة برمجة تطبيقات جلب الويب

استخراج المحتوى من عنوان URL عبر موفّر جلب ويب مهيّأ (Firecrawl أو Jina Reader أو Tavily Extract أو TinyFish Fetch أو Nimble Extract).

الطريقة	المسار	الوصف
POST	`/v1/web/fetch`	جلب/استخلاص عنوان URL — يُتحقق من صحة المتن بواسطة `v1WebFetchSchema`

المصادقة: مفتاح API بنمط Bearer (extractApiKey + isValidApiKey). تُفرض السياسة عبر enforceApiKeyPolicy.

الرجوع الاحتياطي المراعي للحصة (#8297): عند عدم تحديد provider صراحةً، يجري المرور عبر المجموعة (firecrawl → jina-reader → tavily-search → tinyfish → nimble-search) وفق ترتيب أولوية ثابت (ملء الأول أولًا) — يُتخطى الموفّر المهيّأ الذي يخضع لتقييد معدل الطلبات بدلًا من إنهاء الطلب مبكرًا، كما يؤدي فشل قابل لإعادة المحاولة/مرتبط بالحصة من الجهة المصدرية (HTTP 429 دائمًا؛ و402/403 لحصص المستويات المجانية لدى Firecrawl/Tavily/TinyFish — ولكن ليس لدى Jina Reader، وأبدًا ليس لطلب 400 سيئ عادي) إلى الانتقال إلى موفّر تالٍ لم يُجرّب بعد وتتوافر له بيانات اعتماد، وذلك وقت الطلب. عند استنفاد جميع الموفّرين في المجموعة، تُرجع نقطة النهاية استجابة 429 واحدة (مع ترويسة Retry-After) بدلًا من الاستجابة العامة السابقة 400. عند طلب provider صراحةً، لا يوجد أي رجوع احتياطي صامت — بل يُظهر الموفّر الصريح الخاضع لتقييد المعدل أو المتعطل خطأه الخاص (429 إذا كان خاضعًا لتقييد المعدل، وإلا فحالة الجهة المصدرية).

البث عبر WebSocket

GET /v1/ws?handshake=1

يتحقق من صحة مصافحة ترقية WebSocket ويُرجع أمثلة رسائل بروتوكول النقل (request وcancel). يتولى خادم WS المضمّن معالجة إطارات WS الفعلية خارج جدول مسارات Next.js.

المصادقة: مفتاح API بنمط Bearer أثناء المصافحة.

واجهة Responses API عبر WebSocket (لـ codex فقط)

# المضيف:المنفذ نفسه لواجهة HTTP API (الافتراضي 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، ثم ينشئ نفقًا إلى wss://chatgpt.com/backend-api/codex/responses عبر ناقل wreq-js. تُرفض النماذج غير التابعة لـ codex (codex_ws_provider_required). لاستخدام التوجيه بمشاركة الحصة، استخدم model: "qtSd/<group>/codex/<model>". جرى التنفيذ في app/server-ws.mjs + scripts/dev/responses-ws-proxy.mjs + src/app/api/internal/codex-responses-ws/route.ts.

المصادقة: مفتاح API بنمط Bearer أثناء المصافحة. يجب أن يكون خادم HTTP المضمّن (server-ws.mjs) هو نقطة الدخول النشطة (وهو كذلك افتراضيًا عند وجود app/server-ws.mjs).

معرّف النموذج: استخدم معرّف ChatGPT المجرّد (من دون البادئة `codex/`)

تتحقق Codex CLI الخاصة بـ OpenAI من اسم النموذج من جانب العميل عندما تكون supports_websockets = true، كما ترفض المعرّفات المسبوقة باسم الموفّر مثل codex/gpt-5.5 (The 'codex/gpt-5.5' model is not supported when using Codex with a ChatGPT account). أرسل المعرّف المجرّد (مثل gpt-5.5). جسر OmniRoute مخصص لـ codex فقط، لذا يعيد تحليل المعرّف المجرّد باعتباره نموذج codex (resolveCodexWsModelInfo) قبل إنشاء النفق إلى الجهة المصدرية — رغم أن gpt-5.5 المجرّد كان سيُوجَّه بخلاف ذلك إلى موفّر آخر عبر HTTP.

تهيئة OpenAI Codex CLI

وجّه Codex CLI إلى OmniRoute بإضافة موفّر مخصص يدعم WebSocket إلى ~/.codex/config.toml (استخدم CODEX_HOME منفصلًا لتجنب تعديل تهيئة موجودة):

model = "gpt-5.5"                 # معرّف مجرّد — وليس "codex/gpt-5.5"
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # بلا شرطة مائلة لاحقة؛ يُشتق عنوان WS (استخدم https/wss في الإنتاج)
wire_api = "responses"                    # القيمة الوحيدة المدعومة منذ فبراير 2026
supports_websockets = true                # يفعّل ناقل Responses-over-WS
env_key = "OMNIROUTE_API_KEY"             # يحتوي على مفتاح 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` + رمزًا مميزًا)

المصادقة: مفتاح API من نوع Bearer ‏(isAuthenticated).

الاستخدام بالخدمة الذاتية (`/api/usage/om-usage`)

يمكن لأي مفتاح API قراءة استخدامه وحصصه الخاصة به — من دون مصادقة إدارية. هذه هي نقطة النهاية التي يستخدمها العميل (CLI، أو لوحة OmniCopilot) لعرض إنفاق حامل المفتاح.

# الصيغة النصية (العقد التاريخي — نص عادي لطرفية)
curl -H "Authorization: Bearer <your-api-key>" \
  http://localhost:20128/api/usage/om-usage

# الصيغة المنظمة — التي تستخدمها واجهة المستخدم
curl -H "Authorization: Bearer <your-api-key>" \
  "http://localhost:20128/api/usage/om-usage?format=json"

يجب أن يكون الخيار allowUsageCommand مفعّلًا للمفتاح (يكون معطّلًا افتراضيًا — ويبدّله مدير مفاتيح API في لوحة المعلومات لكل مفتاح). من دونه، تستجيب نقطة النهاية بالرمز 403.

يعيد ?format=json بنية مميّزة لكي لا يقرأ المستدعي مطلقًا حقل بيانات من استجابة رفض. عند النجاح:

{
  "allowed": true,
  // لا يظهر إلا عندما يكون المفتاح قد اختار حدود استخدام خاصة بكل مفتاح (يومية/أسبوعية بالدولار الأمريكي):
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // لقطة حصة المزوّد المحدد، أو null عندما لا يكون أي شيء مخزّنًا مؤقتًا بعد:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // لقطة كل اتصال، لكي تتمكن واجهة المستخدم من عرض عدة مزوّدين جنبًا إلى جنب:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}

عند الرفض (401 لمفتاح غير صالح / 403 لعدم السماح)، يعيد المسار نفسه { "allowed": false, "error": { "message": "…" } } — تختلف حالة وجود personal/provider مع كونه فارغًا (المفتاح مسموح، لكن لم تُعرف أي بيانات بعد) عن حالة الرفض، ولا تميّز بينهما إلا صيغة JSON.

المصادقة: مفتاح API من نوع Bearer الخاص بالمستدعي، ويُتحقق منه باستخدام 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
  }
}

التأثير في زمن الاستجابة

يقدّم تطابق ذاكرة التخزين المؤقت الدلالية الاستجابة من الذاكرة المؤقتة من دون إجراء استدعاء إلى المصدر العلوي، ولذلك تكون قيمة X-OmniRoute-Response-Latency المُبلّغ عنها قريبة من الصفر (بغض النظر عن زمن استجابة المصدر العلوي الأصلي). يجب على العملاء الحساسين لزمن الاستجابة (الاختبارات المعيارية، ومراقبة p50/p99) التحقق من ترويسة الاستجابة X-OmniRoute-Cache-Latency:

القيمة	المعنى
`synthetic`	قُدّمت الاستجابة من ذاكرة التخزين المؤقت؛ وزمن الاستجابة ليس زمنًا حقيقيًا للمصدر العلوي
(غائبة)	الاستجابة واردة من استدعاء حقيقي إلى المصدر العلوي

تجاوز ذاكرة التخزين المؤقت لكل مفتاح

يمكن لمفاتيح API إلغاء الاشتراك في عمليات القراءة من ذاكرة التخزين المؤقت الدلالية عبر cacheDefaultMode:

القيمة	السلوك
`legacy`	سلوك ذاكرة التخزين المؤقت العادي (الافتراضي)
`bypass`	تخطي البحث في ذاكرة التخزين المؤقت بالكامل؛ والاتصال دائمًا بالمصدر العلوي

يُضبط عند إنشاء المفتاح (POST /api/keys) أو تحديثه (PATCH /api/keys/[id]):

{ "cacheDefaultMode": "bypass" }

التجاوز لكل طلب

يمكن لأي طلب تجاوز ذاكرة التخزين المؤقت بغض النظر عن إعدادات المفتاح:

X-OmniRoute-No-Cache: true

لوحة المعلومات والإدارة

مسارات الإدارة (/api/* باستثناء المصادقة العامة/تسجيل الدخول) غير مصرّح بالوصول إليها باستخدام مفاتيح API العادية الخاصة بالاستدلال. للاطلاع على فئات بيانات الاعتماد والنطاقات وأمثلة curl: مصادقة الإدارة.

المصادقة

نقطة النهاية	الطريقة	الوصف
`/api/auth/login`	POST	تسجيل الدخول
`/api/auth/logout`	POST	تسجيل الخروج
`/api/settings/require-login`	GET/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	التحقق من صحة إعدادات المزوّد
`/api/providers/bulk`	POST	إضافة مفاتيح API بشكل جماعي لمزوّد واحد
`/api/providers/import`	POST	استيراد قائمة غير متجانسة من المزوّدين من ملف CSV/JSON جرى تحليله (#6836)؛ نتائج فشل جزئي لكل صف
`/api/provider-nodes*`	طرق مختلفة	إدارة عُقد المزوّد
`/api/provider-models`	GET/POST/PATCH/DELETE	النماذج المخصّصة (إضافة، تحديث، إخفاء/إظهار، حذف)

تدفقات 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/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	مسح صفوف سجل الطلبات وملفات سجل الاستدعاءات المحلية

السياق والضغط

Endpoint	الطريقة	الوصف
`/api/compression/preview`	POST	معاينة ضغط off/lite/standard/aggressive/ultra/RTK/stacked
`/api/compression/language-packs`	GET	سرد حزم لغات Caveman المتاحة
`/api/compression/rules`	GET	سرد البيانات الوصفية لقواعد Caveman
`/api/context/caveman/config`	GET/PUT	اسم مستعار للإعدادات الخاصة بـ Caveman
`/api/context/rtk/config`	GET/PUT	إعدادات خاصة بـ RTK، بما في ذلك عوامل التصفية المخصصة والاحتفاظ بالمخرجات الخام
`/api/context/rtk/filters`	GET	كتالوج عوامل تصفية RTK وتشخيصات عوامل التصفية المخصصة
`/api/context/rtk/test`	POST	تشغيل معاينة/اختبار RTK على حمولة نصية
`/api/context/rtk/raw-output/[id]`	GET	قراءة المخرجات الخام المنقحة والمحتفظ بها باستخدام معرّف المؤشر
`/api/context/combos`	GET/POST	سرد/إنشاء تركيبات الضغط
`/api/context/combos/[id]`	GET/PUT/DELETE	تفاصيل/تحديث/حذف تركيبة الضغط
`/api/context/combos/[id]/assignments`	GET/PUT	تعيين تركيبات الضغط إلى تركيبات التوجيه
`/api/context/analytics`	GET	اسم مستعار لتحليلات الضغط

المراقبة

Endpoint	الطريقة	الوصف
`/api/sessions`	GET	تتبع الجلسات النشطة
`/api/rate-limits`	GET	حدود المعدل لكل حساب
`/api/monitoring/health`	GET	فحص السلامة + ملخص المزوّد (`catalogCount` و`configuredCount` و`activeCount` و`monitoredCount`). يتضمن عرض الإدارة `credentialHealth`: قيمًا قياسية لذاكرة التخزين المؤقت للفحوصات، و`failedConnections` عندما تكون `failed>0`، و`staleDbNonOkCount` (قيمة `test_status` الثابتة في SQLite، وليست المقياس). راجع MONITORING_GUIDE.md.
`/api/cache/stats`	GET/DELETE	إحصاءات ذاكرة التخزين المؤقت / مسحها
`/api/modality-bridge/stats`	GET	قيم `attempts` في الذاكرة، وعمليات النجاح/`bridged`، والإخفاقات، وإصابات ذاكرة التخزين المؤقت، و`totalLatencyMs`، و`latencySamples`، و`averageLatencyMs` المحسوب بناءً على عدد العينات، ووقت آخر استخدام (تُعاد التهيئة عند إعادة التشغيل؛ تتطلب مصادقة إدارية)
`/api/modality-bridge/video/runtime`	GET	فحص صارم للاتصال المحلي الموثوق قبل المصادقة الإدارية/الفحص؛ حالة توفر FFmpeg/ffprobe وإصداراتهما بعد تنقيحها (دون تخزين)
`/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`

تحاكي نقاط النهاية هذه تنسيق واجهة API الخاصة بـ Gemini للعملاء الذين يتوقعون توافقًا أصليًا مع Gemini SDK.

واجهات API الداخلية / واجهات النظام

نقطة النهاية	الطريقة	الوصف
`/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": "مرحبًا، هذا هو المحتوى الصوتي المنسوخ.",
  "task": "transcribe",
  "language": "en",
  "duration": 12.5
}

أمثلة على معرّفات النماذج: openai/whisper-1 (يتطلب مفتاح OpenAI)، openrouter/deepgram/nova-3 (يتطلب مفتاح OpenRouter)، deepgram/nova-3 (يتطلب مفتاح Deepgram أصليًا). الطلب المجرّد deepgram/nova-3 لا يستخدم OpenRouter.

التنسيقات المدعومة: mp3، wav، m4a، flac، ogg، webm.

التوافق مع Ollama

للعملاء الذين يستخدمون تنسيق API الخاص بـ Ollama:

# نقطة نهاية الدردشة (بتنسيق Ollama)
POST /v1/api/chat

# عرض قائمة النماذج (بتنسيق Ollama)
GET /api/tags

تُترجم الطلبات تلقائيًا بين تنسيقات Ollama والتنسيقات الداخلية.

الأسماء البديلة المرمّزة لـ VS Code / من دون ترويسات

استخدم هذه الأسماء البديلة عندما يتعذر على عملية تكامل إدخال ترويسة Authorization وتحتاج إلى تضمين مفتاح API في عنوان URL الأساسي.

# اسم بديل للفهرس بنمط OpenAI
GET /api/v1/vscode/{token}/
GET /api/v1/vscode/{token}/models

# أسماء بديلة للدردشة بنمط OpenAI
POST /api/v1/vscode/{token}/chat/completions
POST /api/v1/vscode/{token}/responses

# أسماء بديلة بنمط Ollama
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags

مثال:

curl https://your-host.example/api/v1/vscode/YOUR_API_KEY/models
curl -X POST https://your-host.example/api/v1/vscode/YOUR_API_KEY/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"auto","messages":[{"role":"user","content":"مرحبًا"}]}'

ملاحظات:

تعيد الأسماء البديلة المرمّزة استخدام معالجات الطلبات نفسها التي تستخدمها /v1/* و/api/tags؛ وتظل بُنى الاستجابات متطابقة.
يُفضّل استخدام Authorization: Bearer ... متى كان العميل يدعم الترويسات المخصصة.
قد تظهر الرموز المميزة المستندة إلى عناوين URL في سجلات الوكيل العكسي وسجل المتصفح وبيانات القياس عن بُعد خارج 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 (وهي منفصلة عن الميزانية المستندة إلى الدولار الأمريكي أعلاه). تُطبَّق مباشرةً ضمن مسار الطلب: عندما يصل استخدام المفتاح خلال النافذة الحالية إلى الحد المسموح به، تُرفض الطلبات مع 429 Too Many Requests. يمكن تحديد نطاق الحدود لنموذج model معيّن أو مزوّد provider معيّن، أو تطبيقها global على المفتاح بأكمله؛ وعندما تتطابق عدة حدود مع طلب، يُطبَّق الحد الأكثر تقييدًا.

# عرض حدود الرموز لمفتاح (يتضمن الاستخدام المباشر ضمن النافذة)
GET /api/usage/token-limits?apiKeyId=key-123

# إنشاء حد للرموز أو تحديثه
POST /api/usage/token-limits
Content-Type: application/json

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

# حذف حد للرموز حسب المعرّف
DELETE /api/usage/token-limits?id=tl-abc

ملاحظات المخطط (setTokenLimitSchema): الحقلان apiKeyId وscopeType (model | provider | global) مطلوبان. الحقل scopeValue مطلوب ما لم تكن قيمة scopeType هي global (على سبيل المثال، معرّف نموذج لنطاق model أو معرّف مزوّد لنطاق provider). يجب أن تكون قيمة tokenLimit عددًا صحيحًا موجبًا (تُحوَّل من سلسلة نصية). اختياري: id (احذفه للإنشاء وقدّمه للتحديث)، وresetInterval (daily | weekly | monthly، والقيمة الافتراضية monthly)، وresetTime (HH:MM)، وenabled (القيمة الافتراضية true). تُثري استجابات GET كل حد بالحقول tokensUsed وremaining وwindowStart وperiodStartAt وnextResetAt. هذه نقطة نهاية من فئة الإدارة (تُطبَّق المصادقة مركزيًا بواسطة مسار التفويض).

معالجة الطلبات

يرسل العميل طلبًا إلى /v1/*
يستدعي معالج المسار handleChat أو handleEmbedding أو handleAudioTranscription أو handleImageGeneration
يُحدَّد النموذج (مزوّد/نموذج مباشر أو اسم مستعار/تركيبة)
تُحدَّد بيانات الاعتماد من قاعدة البيانات المحلية مع التصفية حسب توفر الحساب
بالنسبة إلى المحادثة: يتحقق handleChatCore من ذاكرة التخزين المؤقت الدلالية/الخاصة بالتوقيع ويحدد إعدادات ضغط التركيبة
يُنفَّذ الضغط الاستباقي قبل الترجمة الخاصة بالمزوّد عندما يكون مفعّلًا (lite أو Caveman أو RTK أو مكدّسًا)
يرسل منفّذ المزوّد الطلب إلى الجهة العليا
تُترجم الاستجابة مجددًا إلى تنسيق العميل (للمحادثة) أو تُعاد كما هي (للتضمينات/الصور/الصوت)
يُسجَّل الاستخدام وتحليلات الضغط وسجلات الطلبات
يُطبَّق البديل عند حدوث أخطاء وفقًا لقواعد التركيبة

المرجع الكامل للبنية: ARCHITECTURE.md

إدارة التركيبات

يمكن أيضًا ربط تركيبات التوجيه عالية المستوى (الملخّصة سابقًا ضمن /api/combos*) بنسبة 1:1 من نمط معرّف نموذج، مما يتيح إعادة توجيه شفافة لمعرّف نموذج بأسلوب OpenAI إلى تركيبة.

الطريقة	المسار	الوصف
GET	`/api/model-combo-mappings`	عرض جميع روابط النموذج→التركيبة
POST	`/api/model-combo-mappings`	إنشاء ربط — النص: `{pattern, comboId, priority?, enabled?, description?}`
GET	`/api/model-combo-mappings/[id]`	استرداد ربط واحد
PUT	`/api/model-combo-mappings/[id]`	تحديث حقول ربط موجود
DELETE	`/api/model-combo-mappings/[id]`	إزالة ربط

المصادقة: جلسة إدارة/مفتاح API (requireManagementAuth).

خطافات الويب

اشتراكات خطافات الويب الصادرة لأحداث 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 من نوع Bearer ‏(isAuthenticated). راجع أيضًا /v1/quotas/check و/v1/issues/report.

بروتوكول الوكلاء

مهام الوكلاء السحابيين (Claude Code وCodex Cloud وOpenHands وغيرها) التي تُنفَّذ عن بُعد نيابةً عن مستخدمي OmniRoute.

الطريقة	المسار	الوصف
GET	`/api/v1/agents/tasks`	سرد المهام — مع معاملات اختيارية `?provider=` و`?status=` و`?limit=` (من 1 إلى 500، والقيمة الافتراضية 50)
POST	`/api/v1/agents/tasks`	إنشاء مهمة — يجري التحقق من صحة المتن بواسطة `CreateCloudAgentTaskSchema` (`providerId` و`prompt` و`source` و`options?`). يُرجع `201` مع مغلف المهمة
DELETE	`/api/v1/agents/tasks?id=...`	حذف مهمة
GET	`/api/v1/agents/tasks/[id]`	قراءة مهمة — يحدّث الحالة تزامنيًا من الوكيل السحابي المصدر عند تعيين `external_id`
POST	`/api/v1/agents/tasks/[id]`	إجراء مميَّز: `{action: "approve"}` أو `{action: "message", message}` أو `{action: "cancel"}`
DELETE	`/api/v1/agents/tasks/[id]`	حذف مهمة محددة حسب المعرّف

المصادقة: مصادقة الإدارة مطلوبة لكل طريقة (requireCloudAgentManagementAuth). قبل v3.8.0، لم تكن هذه المسارات تتطلب مصادقة — راجع الالتزام 588a0333 لمعرفة التغيير غير المتوافق.

# إنشاء مهمة سحابية في Claude Code
curl -X POST http://localhost:20128/api/v1/agents/tasks \
  -H "Authorization: Bearer your-management-key" \
  -H "Content-Type: application/json" \
  -d '{"providerId":"claude-code-cloud","prompt":"Fix the failing test","source":{"repo":"...","branch":"..."}}'

وكلاء الإدارة

وكلاء 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 المبسّطين الموضحين أعلاه — لا توجد في قاعدة الشفرة مسارات فرعية منفصلة لكل معرّف.

المرونة (موسّعة)

يوفّر OmniRoute ثلاث آليات مستقلة للتعامل مع حالات الفشل المؤقت؛ وتتيح نقاط نهاية الإدارة أدناه للمشغّلين قراءتها وتجاوز إعداداتها:

النطاق	تخزين الحالة	القراءة	إعادة الضبط / المسح
قاطع المزوّد	`domain_circuit_breakers` + الذاكرة الداخلية	`/api/monitoring/health`	`POST /api/resilience/reset`
فترة تهدئة الاتصال	`rateLimitedUntil` في اتصالات المزوّد	`/api/rate-limits`، `/api/providers/[id]`	(تُعاد تهيئته تدريجيًا؛ ويمكن مسحه عبر PUT للمزوّد)
حظر النموذج	سجل توافر النماذج في الذاكرة	`GET /api/resilience/model-cooldowns`	`DELETE /api/resilience/model-cooldowns`

تقبل PATCH /api/resilience تجاوزات قاطع المزوّد ضمن providerBreaker.oauth وproviderBreaker.apikey. يدعم كل ملف تعريف الحقول degradationThreshold وfailureThreshold وresetTimeoutMs؛ والحقول نفسها متاحة في لوحة المعلومات ← الإعدادات ← المرونة.

# مسح حظر نموذج واحد
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -H "Content-Type: application/json" \
  -d '{"provider":"openai","model":"gpt-4o-mini"}'

# مسح جميع حالات الحظر
curl -X DELETE http://localhost:20128/api/resilience/model-cooldowns \
  -H "Cookie: auth_token=..." \
  -d '{"all":true}'

للاطّلاع على المرجع المفاهيمي الكامل والقيم الافتراضية للقاطع: راجع CLAUDE.md ← «حالة وقت تشغيل المرونة».

المهارات

إطار عمل للمهارات يتيح توسيع OmniRoute باستخدام معالجات تنفيذية مخصّصة، إلى جانب عمليات التكامل مع الأسواق.

الطريقة	المسار	الوصف
GET	`/api/skills`	عرض المهارات المثبّتة — قابلة للتصفية باستخدام `?q=` و`?mode=on\|off\|auto` و`?source=skillsmp\|skillssh\|local`، مع تقسيم النتائج إلى صفحات
GET	`/api/skills/[id]`	استرداد مهارة واحدة
PUT	`/api/skills/[id]`	تحديث مهارة (الاسم، والوصف، والوضع، والمخطط، والمعالج، والوسوم)
DELETE	`/api/skills/[id]`	إلغاء تثبيت مهارة
POST	`/api/skills/install`	تثبيت مهارة من بيان خام — النص: `{name, version, description, schema:{input, output}, handlerCode, apiKeyId?}`
GET	`/api/skills/executions`	عرض أحدث عمليات تنفيذ المهارات (سجل تدقيق يتضمن المدخلات والمخرجات والمدة)
GET	`/api/skills/marketplace?q=...`	البحث أو عرض القائمة الشائعة من سوق SkillsMP (يتطلب إعداد `skillsmpApiKey`)
POST	`/api/skills/marketplace/install`	تثبيت مهارة حسب المعرّف من SkillsMP
GET	`/api/skills/skillssh?q=&limit=`	البحث في سجل skills.sh
POST	`/api/skills/skillssh/install`	تثبيت مهارة حسب المعرّف من skills.sh

المصادقة: جلسة الإدارة/مفتاح API. تقبل مسارات البحث في السوق إما مصادقة الإدارة أو مفتاح Bearer API ‏(isAuthenticated).

الذاكرة

مخزن دائم للذاكرة الحوارية/الواقعية، محدد النطاق لكل مفتاح API / جلسة.

الطريقة	المسار	الوصف
GET	`/api/memory`	سرد الذكريات — `?apiKeyId=`, `?type=`, `?sessionId=`, `?q=`، مع ترقيم الصفحات باستخدام `offset/limit` أو `page/limit`
POST	`/api/memory`	إنشاء ذاكرة — يتم التحقق من النص بواسطة Zod: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}`
GET	`/api/memory/[id]`	استرداد ذاكرة واحدة
DELETE	`/api/memory/[id]`	حذف ذاكرة
GET	`/api/memory/health`	حالة نظام الذاكرة الفرعي (اتصال قاعدة البيانات، والواجهة الخلفية للتضمينات، وحالة فهرس المتجهات)

المصادقة: جلسة إدارة/مفتاح API (requireManagementAuth). تعداد type:‏ FACTUAL, EPISODIC, SEMANTIC, PROCEDURAL (راجع MemoryType في src/lib/memory/types.ts).

خادم MCP

يتضمن OmniRoute خادم Model Context Protocol مضمّنًا مع 3 وسائل نقل (stdio وSSE وstreamable-http) وأدوات محددة النطاق. تقرأ نقاط نهاية لوحة المعلومات أدناه بيانات الحالة/التدقيق، وتعمل كوسيط لوسائل نقل HTTP.

الطريقة	المسار	الوصف
GET	`/api/mcp/status`	نبضات الاستمرارية، ووسيلة النقل، وحالة الاتصال، وآخر استدعاء، والأدوات الأكثر استخدامًا، ومعدل النجاح خلال 24 ساعة
GET	`/api/mcp/tools`	قائمة بأدوات MCP تتضمن `name`، و`description`، و`scopes`، و`phase`، و`auditLevel`، و`sourceEndpoints`
GET	`/api/mcp/sse`	فتح تدفق SSE لوسيلة نقل SSE (يعيد `503` إذا كان MCP معطّلًا أو كانت وسيلة النقل غير متطابقة)
POST	`/api/mcp/sse`	إرسال إطار JSON-RPC عبر وسيلة نقل SSE
GET	`/api/mcp/stream`	فتح جانب SSE من وسيلة نقل Streamable HTTP (رسائل يبدأها الخادم)
POST	`/api/mcp/stream`	إرسال إطار JSON-RPC عبر وسيلة نقل Streamable HTTP
DELETE	`/api/mcp/stream`	إنهاء جلسة Streamable HTTP
GET	`/api/mcp/audit`	الاستعلام عن سجل التدقيق — `?limit=`، و`?offset=`، و`?tool=`، و`?success=true	false`، و`?apiKeyId=`
GET	`/api/mcp/audit/stats`	إحصاءات تدقيق مجمّعة (الإجماليات، ومعدل النجاح، ومتوسط المدة، والأدوات الأكثر استخدامًا)

المصادقة: تراعي وسائل النقل sse/stream واجهة المصادقة الخاصة بـMCP (مفتاح Bearer API بنطاق mcp)؛ ويمكن قراءة مسارات status/tools/audit* من لوحة المعلومات (لا يلزم إجراء مصادقة إضافية بخلاف إمكانية الوصول إلى مضيف لوحة المعلومات).

تخضع وسيلتا نقل HTTP لكل من settings.mcpEnabled وsettings.mcpTransport — يؤدي عدم تطابق وسيلة النقل إلى إرجاع 400، بينما تؤدي حالة تعطيل MCP إلى إرجاع 503.

خادم A2A

يوفّر OmniRoute نقطة نهاية A2A (من وكيل إلى وكيل) وفق JSON-RPC 2.0، بالإضافة إلى واجهة REST للاستخدام في الفحص/لوحة المعلومات.

JSON-RPC

POST /a2a
Authorization: Bearer your-api-key   # اختياري ما لم يتم تعيين OMNIROUTE_API_KEY
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "وجّه مهمة البرمجة هذه"}]
  }
}

الطرق المدعومة (كلها مشروطة بتفعيل settings.a2aEnabled):

الطريقة	الوصف
`message/send`	تنفيذ متزامن للمهارة؛ يعيد `{task, artifacts, metadata}`
`message/stream`	تنفيذ متدفق عبر SSE لمجموعة المهارات نفسها
`tasks/get`	جلب مهمة باستخدام `taskId`
`tasks/cancel`	إلغاء مهمة باستخدام `taskId`

المهارات المضمّنة: smart-routing، وquota-management، وprovider-discovery، وcost-analysis، وhealth-report.

بطاقة الوكيل

GET /.well-known/agent.json

يعيد بطاقة وكيل A2A العامة (الاسم، والوصف، والإمكانات، ودليل المهارات، ونظام المصادقة) — وتُخزّن مؤقتًا بشكل عام لمدة ساعة واحدة. لا تتطلب مصادقة.

أدوات REST المساعدة

الطريقة	المسار	الوصف
GET	`/api/a2a/status`	حالة تفعيل A2A + إحصاءات المهام + ملخص بطاقة الوكيل المخزّنة مؤقتًا
GET	`/api/a2a/tasks`	سرد المهام — `?state=submitted\|working\|completed\|failed\|cancelled`، و`?skill=`، و`?limit=` (≤200)، و`?offset=`
POST	`/api/a2a/tasks`	(غير منفّذ كأداة REST مساعدة — أنشئ عبر JSON-RPC باستخدام `message/send`)
GET	`/api/a2a/tasks/[id]`	استرداد مهمة واحدة
POST	`/api/a2a/tasks/[id]/cancel`	إلغاء مهمة

المصادقة: تعمل أدوات REST المساعدة دون مصادقة إدارية (قابلة للقراءة من لوحة المعلومات)؛ ويستخدم مسار JSON-RPC‏ /a2a رمز Bearer‏ OMNIROUTE_API_KEY إذا كان مهيّأً.

السحابة والتقييمات والتقدير

الطريقة	المسار	الوصف
POST	`/api/cloud/auth`	التحقق من مفتاح Bearer وإعادة اتصالات المزوّدين المقنّعة + الأسماء البديلة للنماذج لعملاء المزامنة السحابية
POST	`/api/cloud/credentials/update`	تحديث بيانات الاعتماد المشفّرة لمزوّد متزامن مع السحابة
POST	`/api/cloud/model/resolve`	تحويل معرّف نموذج منطقي إلى مزوّد/نموذج فعلي باستخدام جدول التوجيه المحلي
GET	`/api/cloud/models/alias`	سرد الأسماء البديلة للنماذج كما تظهر للمزامنة السحابية
GET	`/api/assess`	قراءة أحدث تصنيفات التقدير (لكل مزوّد/نموذج)
POST	`/api/assess`	تشغيل تقدير — المتن: `{scope: {type:"all"}	{type:"provider", providerId}	{type:"model", modelId}, trigger?}`
GET	`/api/evals`	سرد حزم التقييم المضمّنة + أحدث عمليات التشغيل
POST	`/api/evals`	تشغيل عملية تقييم
POST	`/api/evals/suites`	إنشاء حزمة تقييم مخصّصة — يتم التحقق من المتن باستخدام `evalSuiteSaveSchema`
GET	`/api/evals/suites/[id]`	استرداد حزمة تقييم مخصّصة

المصادقة: يتحقق /api/cloud/auth من مفتاح Bearer مباشرةً؛ وتتطلب مسارات /api/cloud/* و/api/evals/* و/api/assess الأخرى جلسة إدارة/مفتاح API. يستخدم طلب POST إلى /api/assess الدالة validateBody مع مخطط نطاق ذي اتحاد مميّز.

إدارة ACP (بروتوكول عميل الوكيل)

كعمليات فرعية. تدير نقاط النهاية هذه اكتشاف وكلاء ACP وتسجيل الوكلاء المخصصين.

الطريقة	المسار	الوصف
GET	`/api/acp/agents`	سرد جميع وكلاء CLI المعروفين (المدمجين + المخصصين) مع حالة التثبيت والإصدار والملف التنفيذي
POST	`/api/acp/agents`	تسجيل وكيل ACP مخصص أو تحديث ذاكرة التخزين المؤقت — النص: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` أو `{action: "refresh"}`
DELETE	`/api/acp/agents`	إزالة وكيل ACP مخصص — معامل الاستعلام: `?id=<agentId>`

مثال على الاستجابة (GET /api/acp/agents):

{
  "agents": [
    {
      "id": "claude",
      "name": "Claude Code CLI",
      "binary": "claude",
      "version": "1.0.45",
      "installed": true,
      "protocol": "stdio",
      "providerAlias": "claude",
      "isCustom": false
    },
    {
      "id": "my-custom-cli",
      "name": "My Custom CLI",
      "installed": false,
      "protocol": "stdio",
      "providerAlias": "my-provider",
      "isCustom": true
    }
  ],
  "cacheTtlMs": 60000,
  "cacheAge": 1234
}

المصادقة: تتطلب جلسة إدارة (ملف تعريف ارتباط auth_token الخاص بلوحة المعلومات) أو مفتاح API بنطاق الإدارة.

راجع إطار عمل ACP للاطلاع على التفاصيل الكاملة.

التحليلات وقابلية المراقبة

نقاط نهاية للتحليلات في الوقت الفعلي لمراقبة التوجيه والضغط وتنوع المزودين. تُشغّل هذه النقاط صفحات /dashboard/analytics/*.

تحليلات التوجيه التلقائي

الطريقة	المسار	الوصف
GET	`/api/analytics/auto-routing`	إحصاءات مجمّعة للتوجيه التلقائي: إجمالي الاستدعاءات، وتوزيع الاستراتيجيات، وتوزيع المستويات، وأبرز المزودين
GET	`/api/analytics/auto-routing?days=7`	إحصاءات ضمن نافذة زمنية (الافتراضي 24 ساعة)

مثال على الاستجابة:

{
  "window": "24h",
  "totalCalls": 1234,
  "strategyBreakdown": {
    "rules": 800,
    "cost": 200,
    "latency": 150,
    "sla-aware": 50,
    "lkgp": 34
  },
  "tierBreakdown": {
    "ultra": 100,
    "pro": 500,
    "standard": 400,
    "free": 234
  },
  "topProviders": [
    { "provider": "openai", "calls": 500, "avgLatencyMs": 850 },
    { "provider": "anthropic", "calls": 300, "avgLatencyMs": 1200 }
  ]
}

تحليلات الضغط

الطريقة	المسار	الوصف
GET	`/api/analytics/compression`	إحصاءات مجمّعة للضغط: الرموز الموفَّرة، ونسبة التوفير، وتوزيع الأوضاع، واستخدام المحركات

مثال على الاستجابة:

{
  "window": "24h",
  "totalOriginalTokens": 5000000,
  "totalCompressedTokens": 3500000,
  "totalSavings": 1500000,
  "savingsPct": 30.0,
  "modeBreakdown": {
    "lite": 400,
    "standard": 600,
    "aggressive": 100,
    "ultra": 50,
    "rtk": 84
  },
  "engineBreakdown": {
    "caveman": 800,
    "rtk": 434
  }
}

تتبّع تنوع المزودين

الطريقة	المسار	الوصف
GET	`/api/analytics/diversity`	تتبّع التنوع المستند إلى إنتروبيا شانون: يمنع نقاط الفشل المفردة من خلال قياس انتشار الاستخدام بين المزودين

مثال على الاستجابة:

{
  "window": "24h",
  "shannonEntropy": 2.45,
  "maxEntropy": 3.17,
  "diversityRatio": 0.77,
  "providerUsage": {
    "openai": 0.4,
    "anthropic": 0.25,
    "google": 0.2,
    "kiro": 0.15
  },
  "warnings": ["OpenAI accounts for 40% of traffic — consider diversifying"]
}

المصادقة: تتطلب جلسة إدارة أو مفتاح API بنطاق الإدارة.

عمليات الإدارة

نقاط نهاية مخصصة للمسؤولين لإدارة العمليات.

الطريقة	المسار	الوصف
GET	`/api/admin/concurrency`	قراءة حدود التزامن الحالية (العامة + الخاصة بكل مزود)
POST	`/api/admin/concurrency`	تحديث حدود التزامن — النص: `{global?: number, perProvider?: Record<string, number>}`

المصادقة: تتطلب جلسة إدارة بنطاق مسؤول.

إدارة أدوات CLI

إدارة أدوات CLI التي تتكامل مع OmniRoute (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`	حالة وكيل MITM الخاص بـ Antigravity (أداة CLI المسماة "antigravity-mitm")
POST	`/api/cli-tools/antigravity-mitm/alias`	تكوين الأسماء المستعارة لـ antigravity-mitm

المصادقة: تتطلب جلسة إدارة.

مهارات الوكلاء

إدارة مهارات وكلاء الذكاء الاصطناعي (على غرار نماذج GPT المخصصة من OpenAI، ولكن للوكلاء).

الطريقة	المسار	الوصف
GET	`/api/agent-skills`	سرد جميع مهارات الوكلاء (المدمجة + المخصصة)
GET	`/api/agent-skills/[id]`	الحصول على مهارة وكيل محددة
POST	`/api/agent-skills`	إنشاء مهارة وكيل مخصصة — النص: `{name, description, prompt, model?, temperature?}`
PUT	`/api/agent-skills/[id]`	تحديث مهارة وكيل مخصصة
DELETE	`/api/agent-skills/[id]`	حذف مهارة وكيل مخصصة
GET	`/api/agent-skills/[id]/raw`	الحصول على المطالبة الأولية + البيانات الوصفية (من دون تنفيذ)
POST	`/api/agent-skills/generate`	إنشاء مهارة جديدة باستخدام الذكاء الاصطناعي من وصف بلغة طبيعية

المصادقة: تتطلب جلسة إدارة أو مفتاح 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`	تحديث إعدادات الإضافة

المصادقة: تتطلب جلسة إدارة.

راجع إطار الإضافات للاطلاع على التفاصيل الكاملة.

التوجيه الظلي

المقارنة الظلية / أ-ب بين المزوّدين ليست واجهة REST مستقلة — بل تُهيّأ من خلال التوجيه المركب (راجع التركيب التلقائي). تُقدَّم مقاييس المقارنة الخاصة بكل تركيبة عبر GET /api/combos/metrics.

ضوابط الحماية

فحص ضوابط الحماية في وقت التشغيل (اكتشاف معلومات التعريف الشخصية، واكتشاف حقن المطالبات، وربط الرؤية). تعمل ضوابط الحماية مع كل طلب؛ ويمكن إلغاء الاشتراك لكل استدعاء عبر ترويسة الطلب x-omniroute-disabled-guardrails — ولا توجد واجهة دائمة للتمكين/التعطيل.

الطريقة	المسار	الوصف
GET	`/api/guardrails`	سرد ضوابط الحماية المسجلة وحالتها (الاسم / ممكّنة / الأولوية)
POST	`/api/guardrails/test`	إجراء تشغيل تجريبي لمسار ما قبل الاستدعاء على إدخال نموذجي — النص: `{input, disabledGuardrails?}`

المصادقة: تتطلب جلسة إدارة.

راجع الأمان > ضوابط الحماية للاطلاع على التفاصيل الكاملة.

المصادقة

راجع مصادقة الإدارة للتعرّف على عائلات بيانات الاعتماد الأربع (جلسة لوحة المعلومات، ورمز CLI المحلي، وAccess Token بصيغة oma_live_…، ومفتاح API ذي نطاق الإدارة) وكيف تختلف عن مفاتيح الاستدلال.

تستخدم مسارات لوحة المعلومات (/dashboard/*) ملف تعريف الارتباط auth_token
يستخدم تسجيل الدخول تجزئة كلمة المرور المحفوظة؛ مع الرجوع إلى INITIAL_PASSWORD كخيار احتياطي
يمكن تبديل requireLogin عبر /api/settings/require-login
قد تتطلب مسارات /v1/* اختياريًا مفتاح API من نوع Bearer عندما تكون REQUIRE_API_KEY=true
يُقصد بعبارة "رمز الإدارة" / "مفتاح API ذي نطاق الإدارة" في هذا المرجع إحدى العائلات الواردة في ذلك الدليل — وليس نوعًا إضافيًا غير معرّف من الأسرار

تغيير غير متوافق (v3.8.0) — تتطلب الآن /api/v1/agents/tasks/* ونقاط نهاية إدارة فترة التهدئة مصادقة الإدارة (ملف تعريف الارتباط auth_token الخاص بلوحة المعلومات أو مفتاح API ذي نطاق الإدارة). ستتلقى البرامج العميلة التي كانت تستدعي هذه المسارات سابقًا من دون مصادقة الاستجابة 401 Unauthorized. راجع الالتزام 588a0333 (fix(auth): require management auth for agent and cooldown APIs).

145 KiB Raw Blame History Unescape Escape

API Reference (العربية)

جدول المحتويات

إكمالات الدردشة

الرؤوس المخصّصة

عقود الإيجار الحصرية للجلسات المُدارة

x-omniroute-compression

التضمينات

توليد الصور

التعرّف الضوئي على الأحرف في المستندات

تدفّق الاستقصاء في Azure Document Intelligence

مصادقة Vertex AI DeepSeek OCR وتحديد نقطة النهاية

سرد النماذج

بادئات معرّفات النماذج (?prefix=)

متغيرات النماذج من دون تفكير

بيان إضافة المزوّد

نقاط نهاية التوافق

مسارات المزوّد المخصصة

واجهة برمجة تطبيقات الملفات

واجهة برمجة تطبيقات الدفعات

واجهة برمجة تطبيقات البحث

واجهة برمجة تطبيقات جلب الويب

البث عبر WebSocket

واجهة Responses API عبر WebSocket (لـ codex فقط)

معرّف النموذج: استخدم معرّف ChatGPT المجرّد (من دون البادئة codex/)

تهيئة OpenAI Codex CLI

الحصص والإبلاغ عن المشكلات

الاستخدام بالخدمة الذاتية (/api/usage/om-usage)

ذاكرة التخزين المؤقت الدلالية

التأثير في زمن الاستجابة

تجاوز ذاكرة التخزين المؤقت لكل مفتاح

التجاوز لكل طلب

لوحة المعلومات والإدارة

المصادقة

إدارة المزوّدين

تدفقات OAuth

التوجيه والإعدادات

الاستخدام والتحليلات

الإعدادات

السياق والضغط

المراقبة

النسخ الاحتياطي والتصدير/الاستيراد

المزامنة السحابية

الأنفاق

أدوات CLI

وكلاء ACP

المرونة وحدود المعدل

التقييمات

السياسات

الامتثال

v1beta (متوافق مع Gemini)

واجهات API الداخلية / واجهات النظام

إصلاح بيئة OAuth (v3.6.1+)

نسخ الصوت

التوافق مع Ollama

الأسماء البديلة المرمّزة لـ VS Code / من دون ترويسات

القياس عن بُعد

الميزانية

حدود الرموز

معالجة الطلبات

إدارة التركيبات

خطافات الويب

المفاتيح المسجّلة (الإدارة التلقائية)

بروتوكول الوكلاء

وكلاء الإدارة

المرونة (موسّعة)

المهارات

الذاكرة

خادم MCP

خادم A2A

JSON-RPC

بطاقة الوكيل

أدوات REST المساعدة

السحابة والتقييمات والتقدير

إدارة ACP (بروتوكول عميل الوكيل)

التحليلات وقابلية المراقبة

تحليلات التوجيه التلقائي

تحليلات الضغط

تتبّع تنوع المزودين

عمليات الإدارة

145 KiB

Raw Blame History

`x-omniroute-compression`

بادئات معرّفات النماذج (`?prefix=`)

معرّف النموذج: استخدم معرّف ChatGPT المجرّد (من دون البادئة `codex/`)

الاستخدام بالخدمة الذاتية (`/api/usage/om-usage`)