# API Reference (नेपाली)

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

---

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

OmniRoute API को लागि मुख्य सन्दर्भ। यसले सार्वजनिक `/v1` इन्टरफेस र सबैभन्दा धेरै प्रयोग हुने व्यवस्थापन एन्डपोइन्टहरू समेट्छ; मेसिन-पढ्न योग्य [`docs/openapi.yaml`](../openapi.yaml) र `src/app/api/` अन्तर्गतको रुट ट्री विस्तृत स्रोतहरू हुन्।

---

## विषयसूची

- [च्याट कम्प्लिसनहरू](#chat-completions)
- [विशेष प्रबन्धित सत्र लीजहरू](#exclusive-managed-session-leases)
- [इम्बेडिङहरू](#embeddings)
- [छवि उत्पादन](#image-generation)
- [कागजात OCR](#document-ocr)
- [मोडेलहरू सूचीकृत गर्नुहोस्](#list-models)
- [प्रदायक प्लगइन म्यानिफेस्ट](#provider-plugin-manifest)
- [अनुकूलता एन्डपोइन्टहरू](#compatibility-endpoints)
- [फाइलहरू API](#files-api)
- [ब्याचहरू API](#batches-api)
- [खोज API](#search-api)
- [वेबसकेट स्ट्रिमिङ](#websocket-streaming)
- [कोटा र समस्या रिपोर्टिङ](#quotas--issues-reporting)
- [सिमान्टिक क्यास](#semantic-cache)
- [ड्यासबोर्ड र व्यवस्थापन](#dashboard--management)
- [कम्बो व्यवस्थापन](#combo-management)
- [वेबहुकहरू](#webhooks)
- [दर्ता गरिएका कुञ्जीहरू (स्वचालित-व्यवस्थापन)](#registered-keys-auto-management)
- [एजेन्ट प्रोटोकल](#agents-protocol)
- [व्यवस्थापन प्रोक्सीहरू](#management-proxies)
- [लचिलोपन (विस्तारित)](#resilience-extended)
- [सीपहरू](#skills)
- [मेमोरी](#memory)
- [MCP सर्भर](#mcp-server)
- [A2A सर्भर](#a2a-server)
- [क्लाउड, मूल्याङ्कन र आकलन](#cloud-evals--assess)
- [अनुरोध प्रशोधन](#request-processing)
- [प्रमाणीकरण](#authentication)

---

## च्याट कम्प्लिसनहरू

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

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

### अनुकूलन हेडरहरू

| हेडर                     | दिशा        | विवरण                                                                                                                                                                                                                   |
| :----------------------- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-OmniRoute-No-Cache`   | अनुरोध      | क्यास बाइपास गर्न `true` मा सेट गर्नुहोस्                                                                                                                                                                               |
| `x-omniroute-no-memory`  | अनुरोध      | यस अनुरोधको लागि मेमोरी + सीप इन्जेक्सन छोड्न `true` मा सेट गर्नुहोस् (नो-क्यासको नक्कल गर्दछ; प्रति-कल टोकन/लागत ओभरहेडबाट बच्दछ)                                                                                      |
| `X-OmniRoute-Progress`   | अनुरोध      | प्रगति घटनाहरूको लागि `true` मा सेट गर्नुहोस्                                                                                                                                                                           |
| `X-Session-Id`           | अनुरोध      | बाह्य सत्र आत्मीयताका लागि स्टिकी सत्र कुञ्जी                                                                                                                                                                           |
| `x_session_id`           | अनुरोध      | अन्डरस्कोर भेरियन्ट पनि स्वीकार्य छ (प्रत्यक्ष HTTP)                                                                                                                                                                    |
| `X-OmniRoute-Session-Id` | अनुरोध      | कलर-द्वारा-प्रदान गरिएको सत्र/कुराकानी ट्याग (मेमोरीलाई पनि फिड गर्दछ)। उपस्थित हुँदा, प्रति-सत्र लागत एट्रिब्युसन (#8249) को लागि `call_logs.session_tag` मा शब्दशः राखिन्छ — अनुपस्थित हुँदा कहिल्यै संश्लेषित हुँदैन |
| `Idempotency-Key`        | अनुरोध      | डिडुप कुञ्जी (५ सेकेन्डको विन्डो)                                                                                                                                                                                       |
| `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, १० दशमलवमा निश्चित; निःशुल्क/मूल्य नतोकिएकोका लागि `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` (० भन्दा बढी भएमा मात्र), साथै `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` सूची हुनुपर्छ। डाटाबेस म्युटेशन बाउन्ड्रीले कुञ्जी सिर्जना र आंशिक अपडेटहरूमा दुवै फिल्डहरू सँगै लागू गर्दछ।

```http
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 बडीमा जेनेरेसन प्रदान गर्दछ:

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

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

एक सक्रिय लीज मालिकले आफ्नो हालको बाइन्डिङको लागि स्पष्ट रूपमा गोपनीयता-सुरक्षित प्रदर्शन मेटाडेटा अनुरोध गर्न सक्छ:

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

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

यो अप्ट-इन स्थिति कार्य अपारदर्शी मालिक, प्रमाणित प्रबन्धित API कुञ्जी, र एक डाटाबेस लेनदेनमा सही सक्रिय जेनेरेसनद्वारा सुरक्षित गरिएको छ। `displayName` केवल ट्रिम गरिएको कन्फिगर गरिएको जडान नाम हो; यदि कुनै सुरक्षित कन्फिगर गरिएको नाम अवस्थित छैन भने यो `null` हुन्छ। OmniRoute ले कहिल्यै इमेल वा उत्पन्न खाता पहिचान प्रतिस्थापन गर्दैन। प्रदायक मान एक गैर-संवेदनशील प्रदर्शन लेबल हो र कहिल्यै उत्पन्न मिल्दो-प्रदायक पहिचानकर्ता होइन। प्रमाणहरू, टोकनहरू, कुकीहरू, कच्चा जडान वा API कुञ्जी आईडीहरू, मालिक ह्यासहरू, फेन्सिङ गोप्यहरू, र आन्तरिक राउटिङ डाटा समावेश छैनन्।

गलत-कुञ्जी, गलत-मालिक, पुरानो-जेनेरेसन, हराएको, म्याद सकिएको, जारी गरिएको, र अमान्य गरिएका सबै लुकअपहरूले जडान मेटाडेटा बिना नै `409 LEASE_FENCE_STALE` त्रुटि फर्काउँछन्। क्षमता-प्रतीक्षा प्रतिक्रिया प्राप्त गर्ने ग्राहकसँग निरीक्षण गर्न कुनै सक्रिय बाइन्डिङ हुँदैन। जब राउटिङले सक्रिय लीजलाई ट्रान्जिसन गर्छ, उही जेनेरेसन मान्य रहन्छ र स्थितिले स्वचालित रूपमा नयाँ बाइन्डिङ फर्काउँछ, पुरानो कहिल्यै फर्काउँदैन। अवस्थित ग्राहकहरू अपरिवर्तित रहन्छन् किनभने अधिग्रहण, नवीकरण, रिलिज, र प्रतीक्षा प्रतिक्रियाहरूले तिनीहरूको अघिल्लो आकारहरू कायम राख्छन्।

यो सर्भर सम्झौताले स्टक OpenAI Codex `/status` परिवर्तन गर्दैन। स्टक Codex ले हाल यसको मोडेल प्रदायक र निर्मित प्रमाणीकरण/खाता स्थिति रिपोर्ट गर्दछ तर मनमानी अनुकूल प्रदायक खाता मेटाडेटा रेन्डर गर्दैन; पछिको ग्राहक एकीकरणले यो कार्यलाई कल गर्नुपर्छ र `connection.displayName` कसरी प्रदर्शन गर्ने भनेर निर्णय गर्नुपर्छ।

प्रत्येक प्रबन्धित अनुमान अनुरोधले त्यसपछि दुवै नियन्त्रण हेडरहरू प्रदान गर्दछ:

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

सही मालिक, जेनेरेसन, सक्रिय जडान, र प्रमाणित API कुञ्जी प्रत्येक समर्थित अपस्ट्रीम प्रयास गर्नु अघि तुरुन्तै सुरक्षित गरिन्छ। अर्को कुञ्जीसँग मालिक र जेनेरेसन पुन: प्ले गर्दा असफल हुन्छ, भले पनि त्यो कुञ्जीले उही जडानलाई अनुमति दिन्छ। कच्चा मालिकहरू स्थायी रूपमा राखिँदैनन्, लग गरिँदैनन्, अनुरोध स्न्यापसटमा राखिँदैनन्, वा अपस्ट्रीममा फर्वार्ड गरिँदैनन्।

अस्थायी विवादले `Retry-After` र निम्न सहित HTTP `429` फर्काउँछ:

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

यो प्रतिक्रियाको अर्थ केवल यो हो कि सामान्य योग्य सेट गैर-रिक्त थियो र प्रत्येक खाली उम्मेदवार विदेशी सक्रिय लीजद्वारा राखिएको थियो। असमर्थित मोडेल/प्रदायकहरू, नीति बेमेल, कूलडाउन, कोटा, स्वास्थ्य, र अन्य सामान्य योग्यता असफलताहरूले तिनीहरूको अवस्थित OmniRoute प्रतिक्रियाहरू कायम राख्छन्।

### `x-omniroute-compression`

सङ्कुचन योजनाको प्रति-अनुरोध ओभरराइड। उच्चतम प्राथमिकता — राउटिङ-कम्बो ओभरराइड, सक्रिय प्रोफाइल, स्वतः-ट्रिगर, र प्यानल पूर्वनिर्धारितलाई जित्छ। मानहरू:

| मान           | प्रभाव                                                                                                           |
| ------------- | ---------------------------------------------------------------------------------------------------------------- |
| `off`         | यस अनुरोधको लागि कुनै सङ्कुचन छैन।                                                                               |
| `default`     | प्यानल-व्युत्पन्न पूर्वनिर्धारित प्रोफाइल (सक्रिय प्रोफाइललाई बेवास्ता गर्दछ)। हानिपूर्ण इन्जिनहरू बन्द रहन्छन्। |
| `safe`        | केवल डुप्लिकेशन र खाली ठाउँ फोल्डिङ।                                                                             |
| `allow-lossy` | सारांश र शैली पुनर्लेखन सहित यस अनुरोधको लागि अपरेटर योजना राख्नुहोस्।                                           |
| `engine:<id>` | सक्षम हुँदा एकल इन्जिन, जस्तै `engine:rtk`। त्यस इन्जिनको लागि प्रति-अनुरोध अप्ट-इन।                             |
| `<combo>`     | नामद्वारा (केस-संवेदनशील) पहिले, त्यसपछि आईडीद्वारा मिल्ने नाम दिइएको कम्बो।                                     |

नोटहरू:

- अज्ञात मानहरूलाई बेवास्ता गरिन्छ (अनुरोध कहिल्यै अस्वीकृत हुँदैन); रिजोल्युसन सामान्य अपरेटर प्राथमिकतामा पर्छ।
- यदि धेरै कम्बोहरूले एउटै नाम साझा गर्छन् भने, निश्चित मिलानको लागि कम्बो **id** पास गर्नुहोस्।
- `off` वा `default` नाम भएको कम्बोलाई नामद्वारा चयन गर्न सकिँदैन (ती किवर्डहरू पहिले व्याख्या गरिन्छन्); त्यस्तो कम्बोलाई यसको आईडीद्वारा सन्दर्भ गर्नुहोस्।
- मास्टर सङ्कुचन स्विच एक कडा गेट हो: जब सङ्कुचन विश्वव्यापी रूपमा असक्षम हुन्छ, यो हेडरले यसलाई सक्षम गर्न सक्दैन।

लागू गरिएको योजना प्रतिक्रिया हेडरमा प्रतिध्वनित हुन्छ:

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

जहाँ `<source>` मध्ये एक `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, वा `off` हो।

---

## एम्बेडिङहरू

```bash
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-embeddings-v5-text-small`, `jina-reranker-v3.5`) पनि समाधान हुन्छन्। जिना एम्बेड/रिर्याङ्क/वर्गीकरण/सेगमेन्टले पहिले ड्यासबोर्ड `jina-ai` प्रमाणहरू प्रयोग गर्दछ; `JINA_AI_API_KEY` ड्यासबोर्ड कुञ्जी नभएको अवस्थामा मात्र वैकल्पिक रूपमा प्रयोग हुन्छ। `jina-reader` कार्ड रिडर / `r.jina.ai` को लागि मात्र हो (`POST /v1/web/fetch`) र यसले कहिल्यै एम्बेडिङ वा रिर्याङ्क प्रदान गर्दैन।

मल्टिमोडल समर्थन विज्ञापन गर्ने रजिस्ट्री मोडेलहरूले ३२ वटासम्म प्रदायक-तटस्थ संरचित वस्तुहरू पनि स्वीकार गर्छन्। मिडिया वस्तुका प्रकारहरू `text`, `image`, `audio`, `video`, र `document` हुन्। तिनीहरूको मिडिया `source` या त `{"type":"url","url":"https://..."}` वा `{"type":"base64","data":"...","media_type":"..."}` हुन्छ।

जिना v5 ओम्नी (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`, र परिवार उपनाम `jina-ai/jina-embeddings-v5-omni` → omni-small) ले जिनाको नेटिभ EmbeddingsV5Request कागजातहरू पनि स्वीकार गर्दछ र तिनीहरूलाई `https://api.jina.ai/v1/embeddings` मा **अक्षुण्ण रूपमा फर्वार्ड गर्दछ**:

```json
{
  "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 हुन सक्छन्। ओम्नीराउटले ती वस्तुहरूलाई स्ट्रिङमा रूपान्तरण गर्दैन वा नेटिभ छवि URL हरू फेच गर्दैन — जिनाले सार्वजनिक मिडिया आफैं प्राप्त गर्दछ। अतिरिक्त जिना फिल्डहरू (`task`, `normalized`, `truncate`, `embedding_type`) फर्वार्ड गरिन्छन्। पाठ-मात्र जिना SKU हरूले अझै पनि गैर-पाठ कागजातहरू अस्वीकार गर्छन्।

सुरक्षा र यातायात सीमाहरू:

- रिमोट मिडिया URL हरू सार्वजनिक HTTPS हुनुपर्छ। क्यानोनिकल `{type,source:url}` वस्तुहरू सर्भर-साइडबाट (रिडाइरेक्ट पुन: प्रमाणीकरण, टाइमआउट, आकार सीमा, सार्वजनिक DNS, जडान पिनिङ) फेच गरिन्छन् र प्रदायक कल गर्नु अघि इनलाइन गरिन्छन्। जिना-नेटिभ `{image:"https://..."}` वस्तुहरू उही सार्वजनिक-HTTPS जाँच पछि जस्ताको तस्तै फर्वार्ड गरिन्छन्; जिनाले URL फेच गर्दछ।
- इनलाइन base64 मिडिया प्रति वस्तु ८ MiB डिकोड गरिएको र अनुरोधभरि १६ MiB डिकोड गरिएकोमा सीमित छ।

प्रदायक अनुवाद (क्यानोनिकल वस्तुहरू कहिल्यै अपरिवर्तित फर्वार्ड गरिँदैन):

- जिना मल्टिमोडल मोडेलहरू: प्रत्येक शीर्ष-स्तरको वस्तु इनलाइन मिडियाका लागि डेटा URI हरू प्रयोग गरेर एक मोडालिटी-कुञ्जी वस्तु (`text` / `image` / `audio` / `video` / `pdf`) बन्छ; प्रति शीर्ष-स्तर वस्तु एक भेक्टर।
- जेमिनी एम्बेडिङ २ परिवार: एक शीर्ष-स्तरको एरे `content.parts` (`text` वा `inline_data`) सहितको एकल नेटिभ `models/{model}:embedContent` अनुरोध बन्छ।
- स्पष्ट मोडालिटी मेटाडेटा नभएका अज्ञात/गतिशील मोडेलहरूले HTTP 400 सहित संरचित इनपुट अस्वीकार गर्छन्।

```json
{
  "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 फर्काउँछन्। लेगेसी स्ट्रिङ/टोकन अनुरोधहरूमा गैर-इनपुट विस्तार फिल्डहरू अपरिवर्तित रूपमा पास हुन जारी रहन्छन्।

```bash
# सबै एम्बेडिङ मोडेलहरू सूचीबद्ध गर्नुहोस्
GET /v1/embeddings
```

---

## छवि उत्पादन

```bash
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 (स्थानीय)।

```bash
# सबै छवि मोडेलहरू सूचीबद्ध गर्नुहोस्
GET /v1/images/generations
```

---

## कागजात OCR

```bash
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 प्रदायक चयन गर्दछ; एक साधारण मोडेल आईडी (जस्तै `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`                       | सिंक्रोनस, Vertex AI को `openapi/chat/completions` पार्टनर एन्डपोइन्ट मार्फत — प्रमाणीकरण/URL को लागि तल हेर्नुहोस्। |

सबै तीन प्रदायकहरूले उही Mistral-आकारको बडीमा प्रतिक्रिया दिन्छन्:

```json
{
  "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 लाई प्रति सेकेन्ड ३० पटकसम्म पोल गर्छ, यदि गैर-`ok` पोल प्रतिक्रिया वा `"failed"` स्थिति आएमा छिटो असफल हुन्छ (पोल गरिरहँदैन), र यदि प्रयास बजेट सकिएपछि पनि सञ्चालन चलिरहेको छ भने `504` फर्काउँछ। अन्तिम Azure प्रतिक्रियालाई कलरमा फर्काउनु अघि Mistral द्वारा प्रयोग गरिएको `pages`/`markdown` आकारमा सामान्यीकरण गरिन्छ, त्यसैले क्लाइन्ट कोडले प्रदायकलाई विशेष-केस गर्नुपर्दैन।

### Vertex AI DeepSeek OCR प्रमाणीकरण र एन्डपोइन्ट रिजोलुसन

`vertex-deepseek-ocr` ले OmniRoute ले च्याट/छवि ट्राफिक (`open-sse/executors/vertex.ts`) को लागि पहिले नै समर्थन गर्ने उही Vertex AI प्रमाणीकरण पुन: प्रयोग गर्दछ: जडानको API कुञ्जी या त सेवा खाता JSON प्रमाणिकरण (JWT-बियरर प्रवाह मार्फत छोटो अवधिको OAuth पहुँच टोकनको लागि साटिएको) वा पहिले नै बनाइएको OAuth पहुँच टोकन हो जुन जस्ताको तस्तै प्रयोग गरिन्छ। अपस्ट्रिम एन्डपोइन्ट URL Vertex को जेनेरिक `openapi/chat/completions` पार्टनर एन्डपोइन्ट हो, जुन जडानको परियोजना र क्षेत्रबाट बनाइएको हो — एक स्पष्ट `providerSpecificData.project`/`providerSpecificData.region` सधैं प्राथमिकता पाउँछ; अन्यथा परियोजना सेवा खाता JSON को `project_id` बाट व्युत्पन्न हुन्छ र क्षेत्र पूर्वनिर्धारित रूपमा `us-central1` हुन्छ। दुवै रिजोलुसन `open-sse/handlers/ocr.ts` (`resolveVertexOcrAccessToken`, `resolveVertexOcrBaseUrl`) मा हुन्छन्, जुन `handleOcr` मा पठाउनु अघि `src/app/api/v1/ocr/route.ts` द्वारा खपत गरिन्छ।

## मोडेलहरू सूचीकृत गर्नुहोस्

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

→ OpenAI ढाँचामा सबै च्याट, एम्बेडिङ, र छवि मोडेलहरू + कम्बोजहरू फर्काउँछ
```

### मोडेल आईडी उपसर्गहरू (`?prefix=`)

धेरैजसो मोडेलहरू **प्रदायक उपसर्ग** अन्तर्गत विज्ञापन गरिन्छन्। तपाईंले कुन उपसर्ग पाउनुहुन्छ भन्ने कुरा `MODELS_CATALOG_PREFIX_MODE` फिचर फ्ल्यागद्वारा नियन्त्रित हुन्छ, र यसलाई क्वेरी प्यारामिटरको साथ **प्रत्येक अनुरोधमा** ओभरराइड गर्न सकिन्छ — यो सर्भर-व्यापी सेटिङ अरू सबैका लागि परिवर्तन नगरी सफा सूची चाहने ग्राहकका लागि उपयोगी हुन्छ:

```bash
GET /v1/models?prefix=alias        # one id per model — the short alias prefix
GET /v1/models?prefix=dual         # both forms (server default)
GET /v1/models?prefix=canonical    # only the full provider-id prefix
```

| मोड         | उत्सर्जन गर्छ                                           | टिप्पणीहरू                                                                                                                                                                                                     |
| ----------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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 एक्सटेन्सन](../guides/VSCODE-COPILOT.md) ले यही गर्छ।

### सोच्ने क्षमता नभएका मोडेल भेरियन्टहरू

सोच्ने क्षमता भएका Claude मोडेलहरूका लागि, `/v1/models` ले **सोच्ने क्षमता नभएको** भेरियन्टको पनि विज्ञापन गर्छ जसको आईडी `claude-3-omniroute-no-thinking/` बाट सुरु हुन्छ:

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

यो आईडी चयन गर्दा (जस्तै, सधैं `thinking` ब्लक संलग्न गर्ने Claude Code कन्फिगमा) वास्तविक `<provider>/<model>` मा तर्क दमन गरी समाधान हुन्छ — `/v1/messages` पाथमा `thinking:{type:"disabled"}` वा `/v1/chat/completions` पाथमा `reasoning`/`reasoning_effort` फिल्डहरू हटाइन्छन्। यो भेरियन्ट Claude-परिवारका मोडेलहरूका लागि मात्र सूचीबद्ध गरिएको छ जसले सोच्ने क्षमतालाई समर्थन गर्छन् **र** `disabled` लाई सम्मान गर्छन् (त्यसैले, उदाहरणका लागि, `disabled` अस्वीकार गर्ने अनुकूली-मात्र मोडेलहरूलाई बाहिर राखिएको छ)। अपरेटरहरूले `ModelSpec.noThinkingAlias` मार्फत प्रत्येक मोडेलमा भेरियन्टलाई अन वा अफ गर्न सक्छन्।

---

## प्रदायक प्लगइन म्यानिफेस्ट

```bash
GET /api/v1/provider-plugin-manifest
```

बिफ्रोस्ट, CLIProxyAPI, र भविष्यका साइडकार राउटरहरूद्वारा प्रयोग गरिने JSON-सुरक्षित प्रदायक प्लगइन म्यानिफेस्ट फर्काउँछ। प्रतिक्रिया 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 अडियो (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 मध्यस्थताहरू                   |
| 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` + Zod-मान्य JSON बडी (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, आदि, `src/shared/validation/schemas.ts` मा हेर्नुहोस्)। स्कीमा असफल भएमा 4xx फर्काइन्छ।

ग्राहकहरूका लागि जसले `Authorization: Bearer ...` संलग्न गर्न सक्दैनन्, OmniRoute ले URL मा API कुञ्जीहरूलाई क्वेरी-स्ट्रिङ अनुकूलता (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) वा तल दस्तावेज गरिएका समर्पित `/api/v1/vscode/{token}/...` एन्डपोइन्टहरू मार्फत पनि स्वीकार गर्दछ।

```bash
# Rerank (cloud registry provider, or an OpenAI-compatible provider node as "<prefix>/<model>")
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina classify (Foundation API credentials)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina segmenter
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina search (s.jina.ai; provider aliases: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# Moderations
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — returns audio/mpeg (or requested format) body
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Image edit (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# Video / music generation (provider-prefixed model id)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **रिर्याङ्क प्रदायक नोडहरू:** `POST /v1/rerank` ले OpenAI-अनुकूल प्रदायक नोडहरू (oMLX, vLLM, Infinity, TEI गेटवे पछाडि, ...) लाई पनि `<node-prefix>/<model>` को रूपमा सम्बोधन गर्दछ। लुपब्याक नोडहरू (`localhost`, `127.0.0.1`, `172.16.0.0/12`) सधैं योग्य हुन्छन्। अन्य कुनै पनि होस्टमा रहेका नोडहरू — एउटा LAN बक्स वा Tailscale पियर — अपरेटरले `RERANK_REMOTE_PROVIDER_NODES` फिचर फ्ल्याग सक्षम गरेमा **र** नोडको आधार URL ले प्रदायक आउटबाउन्ड URL नीति (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`) पास गरेमा मात्र योग्य हुन्छन्; क्लाउड-मेटाडेटा होस्टहरूमा कहिल्यै मार्गनिर्देशन गरिँदैन। मेमोरी इन्जिनको रिर्याङ्क चरणले लुपब्याक मार्फत यो मार्गलाई कल गर्दछ, त्यसैले मेमोरी सेटिङहरूमा `rerankProviderModel` लाई पनि यही नियमले नियन्त्रण गर्दछ।
>
> **स्थानीय सर्भर आकारहरू:** नोडलाई `<base>/v1/rerank` मा र, 404 मा, `<base>/rerank` (Infinity, TEI) मा कल गरिन्छ। अपस्ट्रिम बडीले Cohere/OpenAI हिज्जे (`documents`, `return_documents`) र TEI हिज्जे (`texts`, `return_text`) दुवै बोक्छ, र अपस्ट्रिम प्रतिक्रिया Cohere खाममा सामान्यीकृत हुन्छ: TEI को खाली `[{index, score, text}]`, पातलो गेटवेहरूबाट `{results: [{index, score}]}`, र Voyage-शैली `{data: [...]}` सबै ग्राहकलाई `{results: [{index, relevance_score, document?}]}` को रूपमा फर्काइन्छ, स्कोर अनुसार क्रमबद्ध र `top_n` मा सीमित।

> **प्रदायक-नोड खोज:** OpenAI-अनुकूल प्रदायक नोडमा रहेका मोडेलहरू `GET /v1/models` मा नोड उपसर्ग अन्तर्गत देखा पर्छन्। एन्डपोइन्ट मेटाडेटा नभएका पङ्क्तिहरू (स्थानीय `/v1/models` सूचीकरणका लागि सामान्य) ले नोडको `apiType` विरासतमा पाउँछन्, त्यसैले `embeddings` नोडका मोडेलहरू `type: "embedding"` हुन्छन् र `rerank` नोडका मोडेलहरू च्याटमा पूर्वनिर्धारित हुनुको सट्टा `type: "rerank"` हुन्छन्; सिंक गरिएको वा म्यानुअल रूपमा थपिएको पङ्क्तिमा स्पष्ट `supportedEndpoints` अझै पनि प्राथमिकतामा रहन्छ।

### समर्पित प्रदायक मार्गहरू

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

प्रदायक उपसर्ग छुटेको खण्डमा स्वचालित रूपमा थपिन्छ। नमिल्ने मोडेलहरूले `400` फर्काउँछन्।

---

## फाइलहरू API

ब्याच इनपुट/आउटपुट र फाइल-उद्देश्य अपलोडका लागि OpenAI-अनुकूल फाइल एन्डपोइन्ट।

| विधि   | मार्ग                    | विवरण                                                                                                                    |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| POST   | `/v1/files`              | फाइल अपलोड गर्नुहोस् (मल्टिपार्ट: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — ५१२ 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)।

---

## ब्याचहरू 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` यदि दर-सीमित छ, अन्यथा अपस्ट्रीम स्थिति) देखाउँछ।

---

## वेबसकेट स्ट्रिमिङ

```bash
GET /v1/ws?handshake=1
```

एक WebSocket अपग्रेड ह्यान्डशेकलाई मान्य गर्दछ र तार प्रोटोकल उदाहरण सन्देशहरू (`request`, `cancel`) फर्काउँछ। वास्तविक WS फ्रेमहरू Next.js मार्ग तालिका बाहिर बन्डल गरिएको WS सर्भरद्वारा ह्यान्डल गरिन्छ।

**प्रमाणीकरण:** ह्यान्डशेकको समयमा Bearer API कुञ्जी।

### वेबसकेटमा प्रतिक्रिया API (कोडेक्स मात्र)

```bash
# 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" } ] }
```

वेबसकेट प्रोक्सीमा प्रतिक्रिया-एपीआई **विशेष रूपमा `codex`** (ChatGPT ब्याकएन्ड) मा तार गरिएको छ। यसले API/ड्यासबोर्ड जस्तै पोर्टमा `/v1/responses`, `/responses`, र `/api/v1/responses` मार्गहरूमा सुन्छ। पहिलो `response.create` फ्रेममा यसले आन्तरिक `codex-responses-ws` ब्रिज मार्फत प्रमाणीकरण + तयारी गर्दछ, एक कोडेक्स OAuth जडान चयन गर्दछ, र `wreq-js` यातायात मार्फत `wss://chatgpt.com/backend-api/codex/responses` मा टनेल गर्दछ। **गैर-कोडेक्स मोडेलहरू अस्वीकृत हुन्छन्** (`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` अवस्थित हुन्छ)।

#### मोडेल आईडी: खाली ChatGPT आईडी प्रयोग गर्नुहोस् (कुनै `codex/` उपसर्ग छैन)

OpenAI **Codex CLI** ले `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 को ब्रिज कोडेक्स-मात्र हो, त्यसैले यसले अपस्ट्रीम टनेल गर्नु अघि खाली आईडीलाई कोडेक्स मोडेल (`resolveCodexWsModelInfo`) को रूपमा पुन: समाधान गर्दछ — यद्यपि खाली `gpt-5.5` अन्यथा HTTP मा अर्को प्रदायकमा मार्ग हुनेछ।

#### OpenAI Codex CLI कन्फिगर गर्दै

`~/.codex/config.toml` मा WebSocket समर्थनको साथ अनुकूल प्रदायक थपेर Codex CLI लाई OmniRoute मा देखाउनुहोस् (अवस्थित कन्फिगलाई नछुनको लागि छुट्टै `CODEX_HOME` प्रयोग गर्नुहोस्):

```toml
model = "gpt-5.5"                 # खाली आईडी — "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                # वेबसकेटमा प्रतिक्रिया यातायात सक्षम गर्दछ
env_key = "OMNIROUTE_API_KEY"             # OmniRoute API कुञ्जी राख्छ (Bearer)
```

```bash
export OMNIROUTE_API_KEY=sk-...           # एक OmniRoute API कुञ्जी (कुनै पनि कुञ्जी यदि REQUIRE_API_KEY=false)
codex exec "Responda apenas: PONG"
```

CLI ले `base_url + /responses` लाई WebSocket मा अपग्रेड गर्दछ र OmniRoute ले यसलाई चयन गरिएको कोडेक्स OAuth जडानमा टनेल गर्दछ। स्थानीय सर्भर विरुद्ध अन्त-देखि-अन्त मान्य गरिएको: ChatGPT ले `codex.rate_limits` + `response.created` फर्काउँछ र पूरा स्ट्रिम गर्दछ।

---

## कोटा र समस्या रिपोर्टिङ

| Method | Path                | Description                                                                                         |
| ------ | ------------------- | --------------------------------------------------------------------------------------------------- |
| GET    | `/v1/quotas/check`  | दर्ता गरिएको कुञ्जी जारी गर्नु अघि `provider` + `accountId` को लागि कोटा पूर्व-प्रमाणीकरण गर्नुहोस् |
| POST   | `/v1/issues/report` | गिटहबमा कोटा/कुञ्जी जारी गर्ने विफलता रिपोर्ट गर्नुहोस् (`GITHUB_ISSUES_REPO` + टोकन आवश्यक छ)      |

**प्रमाणीकरण:** Bearer API कुञ्जी (`isAuthenticated`)।

---

## सेल्फ-सर्भिस उपयोग (`/api/usage/om-usage`)

कुनै पनि API कुञ्जीले **आफ्नो** उपयोग र कोटा पढ्न सक्छ — कुनै व्यवस्थापन प्रमाणीकरण आवश्यक छैन। यो एउटा एन्डपोइन्ट हो जुन क्लाइन्ट (CLI, OmniCopilot प्यानल) ले कुञ्जी धारकलाई उनीहरूको खर्च देखाउन प्रयोग गर्दछ।

```bash
# पाठ फारम (ऐतिहासिक करार — टर्मिनलका लागि सादा पाठ)
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-कुञ्जी प्रबन्धकले यसलाई प्रत्येक कुञ्जीका लागि टगल गर्छ)। यो बिना एन्डपोइन्टले `403` जवाफ दिन्छ।

`?format=json` ले एक विभेदित आकार फर्काउँछ ताकि कलरले अस्वीकृतिबाट डेटा फिल्ड कहिल्यै नपढोस्। सफलतामा:

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

अस्वीकृतिमा (`401` खराब कुञ्जी / `403` अनुमति छैन) उही मार्गले `{ "allowed": false, "error": { "message": "…" } }` फर्काउँछ — एक उपस्थित तर खाली `personal`/`provider` (कुञ्जी अनुमति दिइएको छ, अझै केही सिकिएको छैन) अस्वीकृतिबाट फरक अवस्था हो, र JSON फारमले मात्र तिनीहरूलाई छुट्याउँछ।

**प्रमाणीकरण:** कलरको आफ्नै Bearer API कुञ्जी, `isValidApiKey` मार्फत प्रमाणीकरण गरिएको — यो व्यवस्थापन इन्टरफेस (`/api/keys/…`) होइन, जुन `requireManagementAuth` पछाडि रहन्छ।

---

## सिमान्टिक क्यास

```bash
# क्यास तथ्याङ्क प्राप्त गर्नुहोस्
GET /api/cache/stats

# सबै क्यासहरू खाली गर्नुहोस्
DELETE /api/cache/stats
```

प्रतिक्रिया उदाहरण:

```json
{
  "semanticCache": {
    "memorySize": 42,
    "memoryMaxSize": 500,
    "dbSize": 128,
    "hitRate": 0.65
  },
  "idempotency": {
    "activeKeys": 3,
    "windowMs": 5000
  }
}
```

### विलम्बताको प्रभाव

एक सिमान्टिक क्यास HIT ले **अपस्ट्रिम कल बिना** क्यासबाट प्रतिक्रिया प्रदान गर्दछ, त्यसैले रिपोर्ट गरिएको `X-OmniRoute-Response-Latency` लगभग शून्य हुन्छ (मूल अपस्ट्रिम विलम्बताको परवाह नगरी)। विलम्बता-संवेदनशील क्लाइन्टहरू (बेन्चमार्किङ, p50/p99 निगरानी) ले `X-OmniRoute-Cache-Latency` प्रतिक्रिया हेडर जाँच गर्नुपर्छ:

| Value       | Meaning                                                                  |
| ----------- | ------------------------------------------------------------------------ |
| `synthetic` | क्यासबाट प्रदान गरिएको प्रतिक्रिया; विलम्बता वास्तविक अपस्ट्रिम समय होइन |
| _(absent)_  | वास्तविक अपस्ट्रिम कलबाट प्रतिक्रिया                                     |

### प्रति-कुञ्जी क्यास बाइपास

API कुञ्जीहरूले `cacheDefaultMode` मार्फत सिमान्टिक क्यास पढाइबाट अप्ट आउट गर्न सक्छन्:

| Value    | Behavior                                                           |
| -------- | ------------------------------------------------------------------ |
| `legacy` | सामान्य क्यास व्यवहार (पूर्वनिर्धारित)                             |
| `bypass` | क्यास लुकअप पूर्ण रूपमा छोड्नुहोस्; सधैं अपस्ट्रिममा हिट गर्नुहोस् |

कुञ्जी सिर्जना (`POST /api/keys`) वा अद्यावधिक (`PATCH /api/keys/[id]`) गर्दा सेट गर्नुहोस्:

```json
{ "cacheDefaultMode": "bypass" }
```

### प्रति-अनुरोध बाइपास

कुनै पनि अनुरोधले कुञ्जी सेटिङहरूको परवाह नगरी क्यास बाइपास गर्न सक्छ:

```
X-OmniRoute-No-Cache: true
```

## ड्यासबोर्ड र व्यवस्थापन

व्यवस्थापन मार्गहरू (`/api/*` सार्वजनिक auth/login बाहेक) सामान्य अनुमान API कुञ्जीहरूद्वारा **अधिकृत छैनन्**। प्रमाणीकरण परिवारहरू, स्कोपहरू, र curl उदाहरणहरू: [व्यवस्थापन प्रमाणीकरण](../guides/MANAGEMENT-AUTH.md)।

### प्रमाणीकरण

| अन्तिम बिन्दु                 | विधि    | विवरण                     |
| ----------------------------- | ------- | ------------------------- |
| `/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*`       | Various               | प्रदायक नोड व्यवस्थापन                                                                                           |
| `/api/provider-models`       | GET/POST/PATCH/DELETE | अनुकूलित मोडेलहरू (थप्नुहोस्, अद्यावधिक गर्नुहोस्, लुकाउनुहोस्/देखाउनुहोस्, मेटाउनुहोस्)                         |

### OAuth प्रवाहहरू

| अन्तिम बिन्दु                    | विधि    | विवरण               |
| -------------------------------- | ------- | ------------------- |
| `/api/oauth/[provider]/[action]` | Various | प्रदायक-विशेष OAuth |

### राउटिङ र कन्फिग

| अन्तिम बिन्दु         | विधि     | विवरण                                |
| --------------------- | -------- | ------------------------------------ |
| `/api/models/alias`   | GET/POST | मोडेल उपनामहरू                       |
| `/api/models/catalog` | GET      | प्रदायक + प्रकार अनुसार सबै मोडेलहरू |
| `/api/combos*`        | Various  | कम्बो व्यवस्थापन                     |
| `/api/keys*`          | Various  | API कुञ्जी व्यवस्थापन                |
| `/api/pricing`        | GET      | मोडेल मूल्य निर्धारण                 |

### उपयोग र विश्लेषण

| Endpoint                         | Method          | Description                                                                                                                                                                                                                                                                                                 |
| -------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/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) |

### सेटिङहरू

| Endpoint                              | Method        | Description                                                                                                                                                                     |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/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](../guides/THINKING_BUDGET.md) हेर्नुहोस्। |
| `/api/settings/system-prompt`         | GET/PUT       | विश्वव्यापी प्रणाली प्रम्प्ट                                                                                                                                                    |
| `/api/settings/compression`           | GET/PUT       | विश्वव्यापी कम्प्रेसन कन्फिग                                                                                                                                                    |
| `/api/settings/purge-request-history` | POST          | अनुरोध लग पङ्क्तिहरू र स्थानीय कल-लग कलाकृतिहरू खाली गर्नुहोस्                                                                                                                  |

### सन्दर्भ र कम्प्रेसन

| अन्तिम बिन्दु                          | विधि           | विवरण                                                                        |
| :------------------------------------- | :------------- | :--------------------------------------------------------------------------- |
| `/api/compression/preview`             | POST           | अफ/लाइट/मानक/आक्रामक/अल्ट्रा/RTK/स्ट्याक्ड कम्प्रेसनको पूर्वावलोकन गर्नुहोस् |
| `/api/compression/language-packs`      | GET            | उपलब्ध केभम्यान भाषा प्याकहरू सूचीबद्ध गर्नुहोस्                             |
| `/api/compression/rules`               | GET            | केभम्यान नियम मेटाडेटा सूचीबद्ध गर्नुहोस्                                    |
| `/api/context/caveman/config`          | GET/PUT        | केभम्यान-विशेष सेटिङ उपनाम                                                   |
| `/api/context/rtk/config`              | GET/PUT        | RTK-विशेष सेटिङहरू, अनुकूलन फिल्टरहरू र कच्चा-आउटपुट प्रतिधारण सहित          |
| `/api/context/rtk/filters`             | GET            | RTK फिल्टर सूची र अनुकूलन-फिल्टर निदान                                       |
| `/api/context/rtk/test`                | POST           | पाठ पेलोड विरुद्ध RTK पूर्वावलोकन/परीक्षण चलाउनुहोस्                         |
| `/api/context/rtk/raw-output/[id]`     | GET            | सूचक आईडी द्वारा राखिएको सम्पादित कच्चा आउटपुट पढ्नुहोस्                     |
| `/api/context/combos`                  | GET/POST       | कम्प्रेसन कम्बो सूची/सिर्जना गर्नुहोस्                                       |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | कम्प्रेसन कम्बो विवरण/अद्यावधिक/मेट्नुहोस्                                   |
| `/api/context/combos/[id]/assignments` | GET/PUT        | राउटिङ कम्बोहरूमा कम्प्रेसन कम्बोहरू असाइन गर्नुहोस्                         |
| `/api/context/analytics`               | GET            | कम्प्रेसन एनालिटिक्स उपनाम                                                   |

### अनुगमन

| अन्तिम बिन्दु                        | विधि       | विवरण                                                                                                                                                                                                                                                                                                                                                                                           |
| :----------------------------------- | :--------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | सक्रिय सत्र ट्र्याकिङ                                                                                                                                                                                                                                                                                                                                                                           |
| `/api/rate-limits`                   | GET        | प्रति-खाता दर सीमाहरू                                                                                                                                                                                                                                                                                                                                                                           |
| `/api/monitoring/health`             | GET        | स्वास्थ्य जाँच + प्रदायक सारांश (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`)। व्यवस्थापन दृश्यमा `credentialHealth` समावेश छ: प्रोब-क्यास स्केलरहरू, `failedConnections` जब `failed>0`, र `staleDbNonOkCount` (SQLite स्टिकी `test_status`, गेज होइन)। [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status) हेर्नुहोस्। |
| `/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`) आवश्यक पर्दछ। प्रदायक ब्रेकर बनाम जडान कूलडाउन बनाम मोडेल लकआउटको पूर्ण विवरणका लागि [लचिलोपन (विस्तारित)](#resilience-extended) हेर्नुहोस्।

### मूल्याङ्कनहरू

| अन्तिम बिन्दु | विधि     | विवरण                                                         |
| :------------ | :------- | :------------------------------------------------------------ |
| `/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 अनुकूलताको अपेक्षा गर्छन्।

### आन्तरिक / प्रणाली API हरू

| अन्तिम बिन्दु            | विधि | विवरण                                                         |
| ------------------------ | ---- | ------------------------------------------------------------- |
| `/api/init`              | GET  | अनुप्रयोग प्रारम्भिकरण जाँच (पहिलो पटक चलाउँदा प्रयोग गरिन्छ) |
| `/api/tags`              | GET  | ओलामा-अनुकूल मोडेल ट्यागहरू (ओलामा क्लाइन्टहरूको लागि)        |
| `/api/restart`           | POST | सर्भरलाई सहज रूपमा पुनः सुरु गर्न ट्रिगर गर्नुहोस्            |
| `/api/shutdown`          | POST | सर्भरलाई सहज रूपमा बन्द गर्न ट्रिगर गर्नुहोस्                 |
| `/api/system/env/repair` | POST | OAuth प्रदायक वातावरण चरहरू मर्मत गर्नुहोस्                   |

> **नोट:** यी अन्तिम बिन्दुहरू प्रणालीद्वारा आन्तरिक रूपमा वा ओलामा क्लाइन्ट अनुकूलताका लागि प्रयोग गरिन्छन्। तिनीहरू सामान्यतया अन्तिम प्रयोगकर्ताहरूद्वारा बोलाइँदैनन्।

### OAuth वातावरण मर्मत _(v3.6.1+)_

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

{
  "provider": "claude-code"
}
```

एक विशिष्ट प्रदायकको लागि हराएको वा बिग्रिएको OAuth वातावरण चरहरू मर्मत गर्दछ। फर्काउँछ:

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

---

## अडियो ट्रान्सक्रिप्शन

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

कुनै पनि कन्फिगर गरिएको STT प्रदायक प्रयोग गरेर अडियो फाइलहरू ट्रान्सक्राइब गर्नुहोस्। पहिलो पाथ
सेगमेन्टले नेटिभ प्रदायक (`openai/…`, `deepgram/…`) चयन गर्दछ। अन्य विक्रेताको
मोडेल पुन: निर्यात गर्ने गेटवेहरूले योग्य आईडी (`openrouter/deepgram/nova-3`) प्रयोग गर्छन्।

**अनुरोध:**

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

**प्रतिक्रिया:**

```json
{
  "text": "Hello, this is the transcribed audio content.",
  "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 ढाँचा प्रयोग गर्ने क्लाइन्टहरूका लागि:

```bash
# च्याट एन्डपोइन्ट (ओलामा ढाँचा)
POST /v1/api/chat

# मोडेल सूचीकरण (ओलामा ढाँचा)
GET /api/tags
```

अनुरोधहरू Ollama र आन्तरिक ढाँचाहरू बीच स्वचालित रूपमा अनुवाद हुन्छन्।

## टोकनाइज्ड VS कोड / हेडरलेस उपनामहरू

यी उपनामहरू प्रयोग गर्नुहोस् जब एकीकरणले `Authorization` हेडर इन्जेक्ट गर्न सक्दैन र API कुञ्जीलाई आधार URL मा इम्बेड गर्न आवश्यक हुन्छ।

```bash
# 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

# ओलामा-शैली उपनामहरू
POST /api/v1/vscode/{token}/api/chat
GET /api/v1/vscode/{token}/api/tags
```

उदाहरण:

```bash
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 बाहिरको टेलिमेट्रीमा देखा पर्न सक्छन्। तिनीहरूलाई अनुकूलता विकल्पको रूपमा व्यवहार गर्नुहोस्, पूर्वनिर्धारित प्रमाणीकरण मोडको रूपमा होइन।

---

## टेलिमेट्री

```bash
# प्रदायक अनुसार विलम्बता टेलिमेट्री सारांश प्राप्त गर्नुहोस् (p50/p95/p99)
GET /api/telemetry/summary
```

**प्रतिक्रिया:**

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

---

## बजेट

```bash
# सबै 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` रूपमा लागू गर्न सकिन्छ; जब धेरै सीमाहरूले अनुरोधसँग मेल खान्छन्, सबैभन्दा प्रतिबन्धात्मक सीमाले जित्छ।

```bash
# एउटा कुञ्जीको टोकन सीमाहरू सूची गर्नुहोस् (प्रत्यक्ष विन्डो प्रयोग समावेश गर्दछ)
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` सँग समृद्ध गर्दछ। यो एक व्यवस्थापन-वर्ग एन्डपोइन्ट हो (authz पाइपलाइन द्वारा केन्द्रीय रूपमा auth लागू गरिएको)।

## अनुरोध प्रशोधन

1.  ग्राहकले `/v1/*` मा अनुरोध पठाउँछ
2.  मार्ग ह्यान्डलरले `handleChat`, `handleEmbedding`, `handleAudioTranscription`, वा `handleImageGeneration` लाई कल गर्छ
3.  मोडेल समाधान गरिन्छ (प्रत्यक्ष प्रदायक/मोडेल वा उपनाम/कम्बो)
4.  खाता उपलब्धता फिल्टरिङ सहित स्थानीय DB बाट प्रमाणहरू चयन गरिन्छ
5.  च्याटको लागि: `handleChatCore` ले सिमान्टिक/हस्ताक्षर क्यास जाँच गर्छ र कम्बो कम्प्रेसन सेटिङहरू समाधान गर्छ
6.  सक्रिय कम्प्रेसन प्रदायक अनुवाद अघि चल्छ जब सक्षम हुन्छ (`lite`, Caveman, RTK, वा स्ट्याक्ड)
7.  प्रदायक कार्यकारीले अपस्ट्रिम अनुरोध पठाउँछ
8.  प्रतिक्रिया ग्राहक ढाँचामा अनुवाद गरिन्छ (च्याट) वा जस्ताको तस्तै फर्काइन्छ (एम्बेडिङ/छवि/अडियो)
9.  प्रयोग, कम्प्रेसन विश्लेषण, र अनुरोध लगहरू रेकर्ड गरिन्छ
10. कम्बो नियमहरू अनुसार त्रुटिहरूमा फलब्याक लागू हुन्छ

पूर्ण वास्तुकला सन्दर्भ: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## कम्बो व्यवस्थापन

उच्च-स्तरको राउटिङ कम्बोहरू (पहिले नै `/api/combos*` अन्तर्गत सारांशित) लाई मोडेल id ढाँचाबाट 1:1 म्याप गर्न सकिन्छ, जसले OpenAI-शैलीको मोडेल id लाई कम्बोमा पारदर्शी पुनर्निर्देशन गर्न अनुमति दिन्छ।

| विधि   | मार्ग                            | विवरण                                                                                    |
| ------ | -------------------------------- | ---------------------------------------------------------------------------------------- |
| 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`)।

---

## वेबहुकहरू

ओम्निरुट घटनाहरू (अनुरोध पूरा, कोटा समाप्त, कुञ्जी रोटेशन, आदि) को लागि आउटबाउन्ड वेबहुक सदस्यताहरू।

| Method | Path                      | Description                                                                    |
| ------ | ------------------------- | ------------------------------------------------------------------------------ |
| 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 कुञ्जीहरू जारी गर्न र घुमाउनको लागि स्वचालित-कुञ्जी व्यवस्थापन उपप्रणालीद्वारा प्रयोग गरिन्छ।

| Method | Path                                  | Description                                                                                                                                                                                                    |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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` पनि हेर्नुहोस्।

---

## एजेन्ट प्रोटोकल

ओम्नीराउट प्रयोगकर्ताहरूको तर्फबाट टाढैबाट कार्यान्वयन गरिएका क्लाउड एजेन्ट कार्यहरू (Claude Code, Codex Cloud, OpenHands, आदि)।

| विधि   | मार्ग                         | विवरण                                                                                                                                                         |
| ------ | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | कार्यहरू सूचीकृत गर्नुहोस् — वैकल्पिक `?provider=`, `?status=`, `?limit=` (१–५००, पूर्वनिर्धारित ५०)                                                          |
| 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 भन्दा पहिले यी अप्रमाणित थिए — ब्रेकिङ परिवर्तनको लागि कमिट `588a0333` हेर्नुहोस्।

```bash
# एउटा 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 ले तीन स्वतन्त्र अस्थायी-असफलता संयन्त्रहरू उजागर गर्दछ; तलका व्यवस्थापन एन्डपोइन्टहरूले अपरेटरहरूलाई तिनीहरूलाई पढ्न र ओभरराइड गर्न दिन्छ:

| दायरा          | अवस्था भण्डारण                        | पढ्नुहोस्                                 | रिसेट / खाली गर्नुहोस्                                            |
| :------------- | :------------------------------------ | :---------------------------------------- | :---------------------------------------------------------------- |
| प्रदायक ब्रेकर | `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` लाई समर्थन गर्दछ; उही फिल्डहरू ड्यासबोर्ड → सेटिङ्स → लचिलोपनमा देखाइन्छ।

```bash
# एउटा मोडेल लकआउट खाली गर्नुहोस्
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`](../../CLAUDE.md) → "Resilience Runtime State" हेर्नुहोस्।

---

## सीपहरू

अनुकूलन कार्यान्वयन योग्य ह्यान्डलरहरू, साथै बजार एकीकरणहरू सहित 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 बाट id द्वारा सीप स्थापना गर्नुहोस्                                                                                             |
| GET    | `/api/skills/skillssh?q=&limit=`  | skills.sh रजिस्ट्री खोज्नुहोस्                                                                                                           |
| POST   | `/api/skills/skillssh/install`    | skills.sh बाट id द्वारा सीप स्थापना गर्नुहोस्                                                                                            |

**प्रमाणीकरण:** व्यवस्थापन सत्र/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` | मेमोरी सबसिस्टमको स्वास्थ्य (DB जडान, एम्बेडिङ ब्याकएन्ड, भेक्टर इन्डेक्स स्थिति)                                             |

**प्रमाणीकरण:** व्यवस्थापन सत्र/API कुञ्जी (`requireManagementAuth`)। `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts` मा `MemoryType` हेर्नुहोस्)।

---

## MCP सर्भर

OmniRoute ले ३ वटा ट्रान्सपोर्ट (stdio, SSE, streamable-http) र स्कोप गरिएका उपकरणहरूसहित एउटा इम्बेडेड मोडेल कन्टेक्स्ट प्रोटोकल सर्भर समावेश गर्दछ। तलका ड्यासबोर्ड एन्डपोइन्टहरूले स्थिति/अडिट डेटा पढ्छन् र HTTP ट्रान्सपोर्टहरूलाई प्रोक्सी गर्छन्।

| विधि | मार्ग | विवरण |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | हार्टबिट, ट्रान्सपोर्ट, अनलाइन स्थिति, अन्तिम कल, शीर्ष उपकरणहरू, २४ घण्टाको सफलता दर |
| 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` | स्ट्रिमेबल HTTP ट्रान्सपोर्टको SSE पक्ष खोल्नुहोस् (सर्भर-सुरु गरिएका सन्देशहरू) |
| POST | `/api/mcp/stream` | स्ट्रिमेबल HTTP ट्रान्सपोर्टमा JSON-RPC फ्रेम पठाउनुहोस् |
| DELETE | `/api/mcp/stream` | स्ट्रिमेबल 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 ले निरीक्षण/ड्यासबोर्ड प्रयोगका लागि A2A (एजेन्ट-टु-एजेन्ट) JSON-RPC 2.0 एन्डपोइन्टका साथै REST र्यापर प्रदान गर्दछ।

### JSON-RPC

```bash
POST /a2a
Authorization: Bearer your-api-key   # वैकल्पिक, OMNIROUTE_API_KEY सेट गरिएको अवस्थामा बाहेक
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "skill": "smart-routing",
    "messages": [{"role": "user", "content": "Route this coding task"}]
  }
}
```

समर्थित विधिहरू (सबै `settings.a2aEnabled` मा आधारित):

| विधि             | विवरण                                                             |
| ---------------- | ----------------------------------------------------------------- |
| `message/send`   | सिंक्रोनस सीप कार्यान्वयन; `{task, artifacts, metadata}` फर्काउँछ |
| `message/stream` | उही सीप सेटको स्ट्रिमिङ SSE कार्यान्वयन                           |
| `tasks/get`      | `taskId` द्वारा कार्य प्राप्त गर्नुहोस्                           |
| `tasks/cancel`   | `taskId` द्वारा कार्य रद्द गर्नुहोस्                              |

निर्मित सीपहरू: `smart-routing`, `quota-management`, `provider-discovery`, `cost-analysis`, `health-report`।

### एजेन्ट कार्ड

```bash
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 कुञ्जी आवश्यक पर्दछ। `/api/assess` POST ले एक विभेदित-युनियन स्कोप स्कीमाको साथ `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`):

```json
{
  "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 Framework](../frameworks/ACP.md) हेर्नुहोस्।

---

## एनालिटिक्स र अवलोकनयोग्यता

राउटिङ, कम्प्रेसन, र प्रदायक विविधताको अनुगमनका लागि वास्तविक-समय एनालिटिक्स एन्डपोइन्टहरू। यिनीहरूले `/dashboard/analytics/*` पृष्ठहरूलाई शक्ति दिन्छन्।

### स्वतः-राउटिङ एनालिटिक्स

| विधि | पाथ                                  | विवरण                                                                                 |
| ---- | ------------------------------------ | ------------------------------------------------------------------------------------- |
| GET  | `/api/analytics/auto-routing`        | समग्र स्वतः-राउटिङ तथ्याङ्कहरू: कुल कलहरू, रणनीति वितरण, टियर वितरण, शीर्ष प्रदायकहरू |
| GET  | `/api/analytics/auto-routing?days=7` | समय-विन्डो गरिएको तथ्याङ्कहरू (पूर्वनिर्धारित २४ घण्टा)                               |

**प्रतिक्रिया उदाहरण**:

```json
{
  "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` | समग्र कम्प्रेसन तथ्याङ्कहरू: बचत गरिएका टोकनहरू, बचत प्रतिशत, मोड वितरण, इन्जिन प्रयोग |

**प्रतिक्रिया उदाहरण**:

```json
{
  "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` | श्यानन एन्ट्रोपी-आधारित विविधता ट्र्याकिङ: प्रदायकको फैलावट मापन गरेर एकल विफलता बिन्दुहरूलाई रोक्छ |

**प्रतिक्रिया उदाहरण**:

```json
{
  "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 कुञ्जी आवश्यक पर्दछ।

---

## प्रशासक कार्यहरू

परिचालन व्यवस्थापनका लागि प्रशासक-मात्र एन्डपोइन्टहरू।

| Method | Path                     | Description                                                                                           |
| ------ | ------------------------ | ----------------------------------------------------------------------------------------------------- |
| GET    | `/api/admin/concurrency` | हालको समवर्ती सीमाहरू पढ्नुहोस् (विश्वव्यापी + प्रति-प्रदायक)                                         |
| POST   | `/api/admin/concurrency` | समवर्ती सीमाहरू अद्यावधिक गर्नुहोस् — body: `{global?: number, perProvider?: Record<string, number>}` |

**Auth:** प्रशासक स्कोपको साथ व्यवस्थापन सत्र आवश्यक छ।

---

## CLI उपकरण व्यवस्थापन

OmniRoute सँग एकीकृत हुने CLI उपकरणहरू (antigravity, commandCode, devin-cli, आदि) व्यवस्थापन गर्नुहोस्। पूर्ण सूचीका लागि [प्रदायक सन्दर्भ](./PROVIDER_REFERENCE.md) हेर्नुहोस्।

| Method | Path                                    | Description                                                                                                                                               |
| ------ | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 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 उपनामहरू कन्फिगर गर्नुहोस्                                                                                                               |

**Auth:** व्यवस्थापन सत्र आवश्यक छ।

---

## एजेन्ट सीपहरू

AI एजेन्ट सीपहरू व्यवस्थापन गर्नुहोस् (OpenAI को अनुकूलित GPT हरू जस्तै तर एजेन्टहरूका लागि)।

| Method | Path                         | Description                                                                                          |
| ------ | ---------------------------- | ---------------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | सबै एजेन्ट सीपहरू सूचीकृत गर्नुहोस् (बिल्ट-इन + अनुकूलित)                                            |
| GET    | `/api/agent-skills/[id]`     | एक विशिष्ट एजेन्ट सीप प्राप्त गर्नुहोस्                                                              |
| POST   | `/api/agent-skills`          | एक अनुकूलित एजेन्ट सीप सिर्जना गर्नुहोस् — body: `{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-उत्पन्न गर्नुहोस्                                                |

**Auth:** व्यवस्थापन सत्र वा व्यवस्थापन-स्कोप गरिएको 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`       | वेबहुकमा परीक्षण घटना पठाउनुहोस्                                            |

**प्रमाणीकरण:** व्यवस्थापन सत्र आवश्यक छ।

पूर्ण घटना प्रकारहरूका लागि [वेबहुक फ्रेमवर्क](../frameworks/WEBHOOKS.md) हेर्नुहोस्।

---

## सीप फ्रेमवर्क

सीपहरू व्यवस्थापन गर्नुहोस् (एजेन्टिक एक्सटेन्सन फ्रेमवर्क)।

| Method | Path                     | विवरण                                                                                          |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | सबै स्थापित सीपहरू सूचीबद्ध गर्नुहोस् (बिल्ट-इन + अनुकूलित)                                    |
| POST   | `/api/skills/install`    | स्थानीय मार्ग वा URL बाट सीप स्थापना गर्नुहोस्                                                 |
| DELETE | `/api/skills/[id]`       | सीप अनइन्स्टल गर्नुहोस्                                                                        |
| PUT    | `/api/skills/[id]`       | सीप सक्षम वा असक्षम गर्नुहोस् — body: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}`    |
| POST   | `/api/skills/executions` | सीप कार्यान्वयन गर्नुहोस् — body: `{skillName, apiKeyId, input?, sessionId?}`                  |
| GET    | `/api/skills/executions` | सबै सीपहरूको लागि कार्यान्वयन इतिहास सूचीबद्ध गर्नुहोस् (`?apiKeyId=` द्वारा फिल्टर गर्नुहोस्) |

**प्रमाणीकरण:** व्यवस्थापन सत्र वा व्यवस्थापन-स्कोप गरिएको API कुञ्जी आवश्यक छ।

पूर्ण विवरणका लागि [सीप फ्रेमवर्क](../frameworks/SKILLS.md) हेर्नुहोस्।

---

## प्लगइनहरू

ओम्नीराउट प्लगइनहरू (तेस्रो-पक्ष एक्सटेन्सनहरू) व्यवस्थापन गर्नुहोस्।

| Method | Path                               | विवरण                                    |
| ------ | ---------------------------------- | ---------------------------------------- |
| 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`       | प्लगइन कन्फिगरेसन अद्यावधिक गर्नुहोस्    |

**प्रमाणीकरण:** व्यवस्थापन सत्र आवश्यक छ।

पूर्ण विवरणका लागि [प्लगइन फ्रेमवर्क](../frameworks/PLUGIN_SDK.md) हेर्नुहोस्।

---

## स्याडो राउटिङ

प्रदायकहरूको स्याडो / A-B तुलना **एक स्ट्यान्डअलोन REST सतह होइन** — यो कम्बो राउटिङ मार्फत कन्फिगर गरिएको छ ([अटो-कम्बो](../routing/AUTO-COMBO.md) हेर्नुहोस्)। प्रति-कम्बो तुलना मेट्रिक्स `GET /api/combos/metrics` द्वारा प्रदान गरिन्छ।

---

## गार्डरेलहरू

रनटाइम गार्डरेलहरू (PII पत्ता लगाउने, प्रम्प्ट इन्जेक्सन पत्ता लगाउने, भिजन ब्रिजिङ) निरीक्षण गर्नुहोस्। गार्डरेलहरू प्रत्येक अनुरोधमा चल्छन्; प्रति-कल अप्ट-आउट `x-omniroute-disabled-guardrails` अनुरोध हेडर मार्फत हुन्छ — त्यहाँ कुनै स्थायी सक्षम/असक्षम सतह छैन।

| Method | Path                   | विवरण                                                                                      |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------ |
| GET    | `/api/guardrails`      | दर्ता गरिएका गार्डरेलहरू र तिनीहरूको स्थिति (नाम / सक्षम / प्राथमिकता) सूचीबद्ध गर्नुहोस्  |
| POST   | `/api/guardrails/test` | नमूना इनपुटमा प्रि-कल पाइपलाइनको ड्राई-रन गर्नुहोस् — body: `{input, disabledGuardrails?}` |

**प्रमाणीकरण:** व्यवस्थापन सत्र आवश्यक छ।

पूर्ण विवरणका लागि [सुरक्षा > गार्डरेलहरू](../security/GUARDRAILS.md) हेर्नुहोस्।

---

---

## प्रमाणीकरण

चार प्रमाणिकरण परिवारहरू (ड्यासबोर्ड सत्र, स्थानीय CLI टोकन, `oma_live_…` पहुँच टोकन, व्यवस्थापन-स्कोप गरिएको API कुञ्जी) र तिनीहरू कसरी अनुमान कुञ्जीहरूबाट भिन्न छन् भनी बुझ्नका लागि [व्यवस्थापन प्रमाणीकरण](../guides/MANAGEMENT-AUTH.md) हेर्नुहोस्।

- ड्यासबोर्ड मार्गहरू (`/dashboard/*`) ले `auth_token` कुकी प्रयोग गर्छन्
- लगइनले सुरक्षित गरिएको पासवर्ड ह्यास प्रयोग गर्छ; `INITIAL_PASSWORD` मा फर्कन्छ
- `/api/settings/require-login` मार्फत `requireLogin` टगल गर्न सकिन्छ
- `/v1/*` मार्गहरूले `REQUIRE_API_KEY=true` हुँदा वैकल्पिक रूपमा Bearer API कुञ्जी आवश्यक पर्छ
- यस सन्दर्भमा "व्यवस्थापन टोकन" / "व्यवस्थापन-स्कोप गरिएको API कुञ्जी" भन्नाले त्यस गाइडमा उल्लेखित परिवारहरू मध्ये एक हो — न कि एक अपरिभाषित अतिरिक्त गोप्य प्रकार।

> **ब्रेकिङ परिवर्तन (v3.8.0)** — `/api/v1/agents/tasks/*` र कुल्डाउन व्यवस्थापन अन्तिम बिन्दुहरूलाई अब **व्यवस्थापन प्रमाणीकरण** (ड्यासबोर्ड `auth_token` कुकी वा व्यवस्थापन-स्कोप गरिएको API कुञ्जी) आवश्यक पर्छ। पहिले यी मार्गहरूलाई अप्रमाणित रूपमा कल गर्ने ग्राहकहरूले `401 Unauthorized` प्राप्त गर्नेछन्। कमिट `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`) हेर्नुहोस्।