# 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) · 🇳🇵 [ne](../../../ne/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) · 🇸🇰 [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)

---

🌐 **භාෂා:** 🇺🇸 [ඉංග්රීසි](./API_REFERENCE.md) | 🇪🇹 [አማርኛ](../i18n/am/docs/reference/API_REFERENCE.md) | 🇸🇦 [العربية](../i18n/ar/docs/reference/API_REFERENCE.md) | 🇦🇿 [Azərbaycan dili](../i18n/az/docs/reference/API_REFERENCE.md) | 🇧🇬 [Български](../i18n/bg/docs/reference/API_REFERENCE.md) | 🇧🇩 [বাংলা](../i18n/bn/docs/reference/API_REFERENCE.md) | 🇧🇦 [Bosanski](../i18n/bs/docs/reference/API_REFERENCE.md) | 🇨🇿 [Čeština](../i18n/cs/docs/reference/API_REFERENCE.md) | 🇩🇰 [Dansk](../i18n/da/docs/reference/API_REFERENCE.md) | 🇩🇪 [Deutsch](../i18n/de/docs/reference/API_REFERENCE.md) | 🇬🇷 [Ελληνικά](../i18n/el/docs/reference/API_REFERENCE.md) | 🇪🇸 [Español](../i18n/es/docs/reference/API_REFERENCE.md) | 🇪🇪 [Eesti](../i18n/et/docs/reference/API_REFERENCE.md) | 🇮🇷 [فارسی](../i18n/fa/docs/reference/API_REFERENCE.md) | 🇫🇮 [Suomi](../i18n/fi/docs/reference/API_REFERENCE.md) | 🇫🇷 [Français](../i18n/fr/docs/reference/API_REFERENCE.md) | 🇮🇪 [Gaeilge](../i18n/ga/docs/reference/API_REFERENCE.md) | 🇮🇳 [ગુજરાતી](../i18n/gu/docs/reference/API_REFERENCE.md) | 🇳🇬 [Hausa](../i18n/ha/docs/reference/API_REFERENCE.md) | 🇮🇱 [עברית](../i18n/he/docs/reference/API_REFERENCE.md) | 🇮🇳 [हिन्दी](../i18n/hi/docs/reference/API_REFERENCE.md) | 🇭🇷 [Hrvatski](../i18n/hr/docs/reference/API_REFERENCE.md) | 🇭🇺 [Magyar](../i18n/hu/docs/reference/API_REFERENCE.md) | 🇦🇲 [Հայերեն](../i18n/hy/docs/reference/API_REFERENCE.md) | 🇮🇩 [Bahasa Indonesia](../i18n/id/docs/reference/API_REFERENCE.md) | 🇳🇬 [Igbo](../i18n/ig/docs/reference/API_REFERENCE.md) | 🇮🇹 [Italiano](../i18n/it/docs/reference/API_REFERENCE.md) | 🇯🇵 [日本語](../i18n/ja/docs/reference/API_REFERENCE.md) | 🇬🇪 [ქართული](../i18n/ka/docs/reference/API_REFERENCE.md) | 🇰🇭 [ខ្មែរ](../i18n/km/docs/reference/API_REFERENCE.md) | 🇮🇳 [ಕನ್ನಡ](../i18n/kn/docs/reference/API_REFERENCE.md) | 🇰🇷 [한국어](../i18n/ko/docs/reference/API_REFERENCE.md) | 🇱🇹 [Lietuvių](../i18n/lt/docs/reference/API_REFERENCE.md) | 🇱🇻 [Latviešu](../i18n/lv/docs/reference/API_REFERENCE.md) | 🇮🇳 [മലയാളം](../i18n/ml/docs/reference/API_REFERENCE.md) | 🇮🇳 [मराठी](../i18n/mr/docs/reference/API_REFERENCE.md) | 🇲🇾 [Bahasa Melayu](../i18n/ms/docs/reference/API_REFERENCE.md) | 🇲🇹 [Malti](../i18n/mt/docs/reference/API_REFERENCE.md) | 🇲🇲 [မြန်မာ](../i18n/my/docs/reference/API_REFERENCE.md) | 🇳🇵 [नेपाली](../i18n/ne/docs/reference/API_REFERENCE.md) | 🇳🇱 [Nederlands](../i18n/nl/docs/reference/API_REFERENCE.md) | 🇳🇴 [Norsk](../i18n/no/docs/reference/API_REFERENCE.md) | 🇮🇳 [ଓଡ଼ିଆ](../i18n/or/docs/reference/API_REFERENCE.md) | 🇮🇳 [ਪੰਜਾਬੀ](../i18n/pa/docs/reference/API_REFERENCE.md) | 🇵🇭 [Filipino](../i18n/phi/docs/reference/API_REFERENCE.md) | 🇵🇱 [Polski](../i18n/pl/docs/reference/API_REFERENCE.md) | 🇵🇹 [Português (Portugal)](../i18n/pt/docs/reference/API_REFERENCE.md) | 🇧🇷 [Português (Brasil)](../i18n/pt-BR/docs/reference/API_REFERENCE.md) | 🇷🇴 [Română](../i18n/ro/docs/reference/API_REFERENCE.md) | 🇷🇺 [Русский](../i18n/ru/docs/reference/API_REFERENCE.md) | 🇱🇰 [සිංහල](../i18n/si/docs/reference/API_REFERENCE.md) | 🇸🇰 [Slovenčina](../i18n/sk/docs/reference/API_REFERENCE.md) | 🇸🇮 [Slovenščina](../i18n/sl/docs/reference/API_REFERENCE.md) | 🇷🇸 [Српски](../i18n/sr/docs/reference/API_REFERENCE.md) | 🇸🇪 [Svenska](../i18n/sv/docs/reference/API_REFERENCE.md) | 🇰🇪 [Kiswahili](../i18n/sw/docs/reference/API_REFERENCE.md) | 🇮🇳 [தமிழ்](../i18n/ta/docs/reference/API_REFERENCE.md) | 🇮🇳 [తెలుగు](../i18n/te/docs/reference/API_REFERENCE.md) | 🇹🇭 [ไทย](../i18n/th/docs/reference/API_REFERENCE.md) | 🇹🇷 [Türkçe](../i18n/tr/docs/reference/API_REFERENCE.md) | 🇺🇦 [Українська](../i18n/uk-UA/docs/reference/API_REFERENCE.md) | 🇵🇰 [اردو](../i18n/ur/docs/reference/API_REFERENCE.md) | 🇺🇿 [Oʻzbekcha](../i18n/uz/docs/reference/API_REFERENCE.md) | 🇻🇳 [Tiếng Việt](../i18n/vi/docs/reference/API_REFERENCE.md) | 🇳🇬 [Yorùbá](../i18n/yo/docs/reference/API_REFERENCE.md) | 🇨🇳 [中文 (简体)](../i18n/zh-CN/docs/reference/API_REFERENCE.md) | 🇹🇼 [中文 (繁體)](../i18n/zh-TW/docs/reference/API_REFERENCE.md)

OmniRoute API සඳහා මූලික යොමුව. මෙය පොදු `/v1` අතුරුමුහුණත සහ වැඩිපුරම භාවිත වන කළමනාකරණ අන්ත ලක්ෂ්ය ආවරණය කරයි; යන්ත්රයෙන් කියවිය හැකි [`docs/openapi.yaml`](../openapi.yaml) සහ `src/app/api/` යටතේ ඇති මාර්ග වෘක්ෂය පරිපූර්ණ මූලාශ්ර වේ.

විශේෂයෙන් අවධානය යොමු කළ OpenAI-අනුකූල ප්රොටෝකෝලය සහ සැපයුම්කරු හැකියා අනුකෘතිය සඳහා,
[`OPENAI_COMPATIBILITY.md`](./OPENAI_COMPATIBILITY.md) බලන්න.

---

## පටුන

- [කතාබස් සම්පූර්ණ කිරීම්](#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 ප්රවාහනය](#websocket-streaming)
- [කෝටා සහ ගැටලු වාර්තා කිරීම](#quotas--issues-reporting)
- [අර්ථවිචාරක හැඹිලිය](#semantic-cache)
- [උපකරණ පුවරුව සහ කළමනාකරණය](#dashboard--management)
- [සංයෝජන කළමනාකරණය](#combo-management)
- [Webhooks](#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` | ඉල්ලීම    | ඇමතුම්කරු සපයන සැසි/සංවාද ටැගය (මතකයට ද දත්ත සපයයි). පවතින විට, එක් සැසියකට පිරිවැය ආරෝපණය කිරීම සඳහා `call_logs.session_tag` වෙත එලෙසම සුරකියි (#8249) — නොමැති විට කිසි විටෙක සංස්ලේෂණය නොකෙරේ         |
| `Idempotency-Key`        | ඉල්ලීම    | අනුපිටපත් ඉවත් කිරීමේ යතුර (තත්පර 5ක කවුළුව)                                                                                                                                                             |
| `X-Request-Id`           | ඉල්ලීම    | විකල්ප අනුපිටපත් ඉවත් කිරීමේ යතුර                                                                                                                                                                        |
| `X-OmniRoute-Cache`      | ප්රතිචාරය | `HIT` හෝ `MISS` (ප්රවාහනය නොවන)                                                                                                                                                                          |
| `X-OmniRoute-Idempotent` | ප්රතිචාරය | අනුපිටපත් ඉවත් කර ඇත්නම් `true`                                                                                                                                                                          |
| `X-OmniRoute-Progress`   | ප්රතිචාරය | ප්රගති ලුහුබැඳීම ක්රියාත්මක නම් `enabled`                                                                                                                                                                |
| `X-OmniRoute-Session-Id` | ප්රතිචාරය | OmniRoute භාවිත කළ ක්රියාත්මක සැසි ID                                                                                                                                                                    |
| `X-OmniRoute-Request-Id` | ප්රතිචාරය | ඉල්ලීම් සහසම්බන්ධතා id (දන්නා විට)                                                                                                                                                                       |
| `X-OmniRoute-Version`    | ප්රතිචාරය | OmniRoute ගොඩනැගීමේ අනුවාදය (සැමවිටම පවතී)                                                                                                                                                               |
| `X-OmniRoute-Cost-Saved` | ප්රතිචාරය | HIT එකකදී හැඹිලිය නිසා වැළකුණු USD පිරිවැය (හැඹිලි හමු සඳහා පමණි)                                                                                                                                        |
| `X-OmniRoute-Decision`   | ප්රතිචාරය | මාර්ගගත කිරීමේ අනුරේඛනය: `strategy=<name>; provider=<alias>; latency_ms=<n>` (`<name>` යනු සංයෝජන උපායමාර්ගයයි, නැතහොත් සංයෝජන නොවන ඉල්ලීමක් සඳහා `single` වේ) — සම්පූර්ණ කිරීමේ ප්රතිචාරවල සැමවිටම පවතී |

> Nginx සටහන: ඔබ යටි ඉරි සහිත ශීර්ෂක මත රඳා පවතින්නේ නම් (උදාහරණයක් ලෙස `x_session_id`), `underscores_in_headers on;` සක්රීය කරන්න.

> **පිරිවැය ටෙලිමෙට්රි ශීර්ෂ:** ප්රවාහනය නොවන සාර්ථක ප්රතිචාරවල `X-OmniRoute-*` පිරිවැය-ටෙලිමෙට්රි කට්ටලයද ඇතුළත් වේ — `X-OmniRoute-Response-Cost` (USD, ස්ථාවර දශම ස්ථාන 10ක්; නොමිලේ/මිල නියම කර නොමැති අවස්ථා සඳහා `0.0000000000`), `X-OmniRoute-Tokens-In` / `X-OmniRoute-Tokens-Out`, `X-OmniRoute-Model`, `X-OmniRoute-Provider`, `X-OmniRoute-Latency-Ms`, `X-OmniRoute-Cache-Hit`, සහ `X-OmniRoute-Fallback-Attempts` (> 0 විට පමණක්), එමෙන්ම `X-OmniRoute-Request-Id` සහ `X-OmniRoute-Version`. මේවා chat completions, `/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` වේ (fail-open).

> **හැඹිලි-ගැළපුම් පිරිවැය අර්ථ විග්රහය:** semantic-cache HIT එකකදී (`X-OmniRoute-Cache-Hit: true`) upstream ඇමතුමක් සිදු නොවන බැවින්, `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 යතුර එක් එක් සහාය දක්වන ඉහළ ධාරා උත්සාහයට පෙර වහාම වැට බැඳ ඇත. වෙනත් යතුරක් සමඟ හිමිකරු සහ පරම්පරාව නැවත ධාවනය කිරීම අසාර්ථක වේ, එම යතුර එකම සම්බන්ධතාවයට ඉඩ දුන්නද. අමු හිමිකරුවන් නොපවතින, ලොග් නොවන, ඉල්ලීම් ස්නැප්ෂොට් එකේ රඳවා නොගන්නා, හෝ ඉහළ ධාරාවට යොමු නොකරයි.

තාවකාලික ගැටුම HTTP `429` `Retry-After` සමඟ සහ:

```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>`     | නම් කරන ලද සංයෝජනයක්, පළමුව නම අනුව (අකුරු සංවේදී නොවන), පසුව හැඳුනුම්පත අනුව ගැලපේ.        |

සටහන්:

- නොදන්නා අගයන් නොසලකා හරිනු ලැබේ (ඉල්ලීම කිසි විටෙක ප්රතික්ෂේප නොවේ); විසඳුම සාමාන්ය ක්රියාකරු ප්රමුඛතාවයට වැටේ.
- සංයෝජන කිහිපයක් නමක් බෙදා ගන්නේ නම්, නියත ගැලපීමක් සඳහා සංයෝජන **හැඳුනුම්පත** ලබා දෙන්න.
- `off` හෝ `default` යන නම ඇති සංයෝජනයක් නම අනුව තෝරා ගත නොහැක (එම මූල පද පළමුව අර්ථකථනය කරනු ලැබේ); එවැනි සංයෝජනයක් එහි හැඳුනුම්පත අනුව යොමු කරන්න.
- ප්රධාන සම්පීඩන ස්විචය දැඩි දොරටුවකි: සම්පීඩනය ගෝලීයව අක්රිය කර ඇති විට, මෙම ශීර්ෂය එය සක්රීය කළ නොහැක.

යොදන ලද සැලැස්ම ප්රතිචාර ශීර්ෂයේ නැවත දෝංකාර දෙයි:

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

මෙහි `<source>` යනු `request-header`, `routing-override`, `active-profile`, `auto-trigger`, `default`, හෝ `off` යන ඒවායින් එකකි.

---

## Embeddings

```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 ආකෘති හැඳුනුම්ද (උදාහරණයක් ලෙස `jina-embeddings-v5-text-small`, `jina-reranker-v3.5`) විසඳනු ලැබේ. Jina embed/rerank/classify/segment සඳහා පළමුව උපකරණ පුවරුවේ `jina-ai` අක්තපත්ර භාවිත වේ; උපකරණ පුවරු යතුරක් නොමැති විට පමණක් `JINA_AI_API_KEY` විකල්පයක් ලෙස භාවිත වේ. `jina-reader` කාඩ්පත Reader / `r.jina.ai` සඳහා පමණක් (`POST /v1/web/fetch`) වන අතර කිසිවිටෙක embeddings හෝ rerank සපයන්නේ නැත.

බහුමාධ්ය සහාය දක්වන රෙජිස්ට්රි ආකෘති, සැපයුම්කරු-ස්වාධීන ව්යුහගත අයිතම 32ක් දක්වාද පිළිගනී.
මාධ්ය අයිතම වර්ග වන්නේ `text`, `image`, `audio`, `video`, සහ `document` ය. ඒවායේ මාධ්ය `source`
එක `{"type":"url","url":"https://..."}` හෝ
`{"type":"base64","data":"...","media_type":"..."}` වේ.

Jina v5 Omni (`jina-ai/jina-embeddings-v5-omni-small`, `jina-ai/jina-embeddings-v5-omni-nano`,
සහ පවුල් අන්වර්ථ නාමය `jina-ai/jina-embeddings-v5-omni` → omni-small) Jina හි ස්වදේශීය
EmbeddingsV5Request ලේඛනද පිළිගෙන ඒවා `https://api.jina.ai/v1/embeddings` වෙත **වෙනස් නොකර යොමු කරයි**:

```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 දත්ත විය හැක. OmniRoute එම වස්තු තන්තු බවට පත් කරන්නේවත් ස්වදේශීය රූප URL ලබාගන්නේවත් නැත — Jina විසින්
පොදු මාධ්ය ලබාගනී. අමතර Jina ක්ෂේත්ර (`task`, `normalized`, `truncate`, `embedding_type`)
යොමු කරනු ලැබේ. පෙළ-පමණක් වන Jina SKU තවමත් පෙළ නොවන ලේඛන ප්රතික්ෂේප කරයි.

ආරක්ෂක සහ ප්රවාහන සීමා:

- දුරස්ථ මාධ්ය URL පොදු HTTPS විය යුතුය. සම්මත `{type,source:url}` අයිතම
  සේවාදායක පාර්ශ්වයෙන් ලබාගෙන (යළි-යොමු නැවත වලංගු කිරීම, කාලසීමාව, ප්රමාණ සීමා, පොදු DNS, සම්බන්ධතා ස්ථාපනය)
  සැපයුම්කරු ඇමතීමට පෙර පේළිගත කරනු ලැබේ. Jina-ස්වදේශීය `{image:"https://..."}` අයිතම
  එම පොදු-HTTPS පරීක්ෂාවෙන් පසු එලෙසම යොමු කරනු ලැබේ; Jina විසින් URL එක ලබාගනී.
- පේළිගත base64 මාධ්ය එක් අයිතමයකට විකේතනය කළ 8 MiB දක්වාත්, ඉල්ලීම පුරා විකේතනය කළ 16 MiB දක්වාත් සීමා වේ.

සැපයුම්කරු පරිවර්තනය (සම්මත අයිතම කිසිවිටෙක වෙනස් නොකර යොමු නොකෙරේ):

- Jina බහුමාධ්ය ආකෘති: සෑම ඉහළ-මට්ටමේ අයිතමයක්ම එක් මාධ්ය-යතුරුගත වස්තුවක් බවට පත්වේ
  (`text` / `image` / `audio` / `video` / `pdf`), පේළිගත මාධ්ය සඳහා data URI භාවිත කරමින්; එක්
  ඉහළ-මට්ටමේ අයිතමයකට එක් දෛශිකයක්.
- Gemini Embedding 2 පවුල: එක් ඉහළ-මට්ටමේ අරාවක්, `content.parts` (`text` හෝ `inline_data`) සහිත තනි ස්වදේශීය
  `models/{model}:embedContent` ඉල්ලීමක් බවට පත්වේ.
- llama.cpp (`llama-cpp/<model>`, දේශීය සේවාදායකය පූරණය කළ ඕනෑම ආකෘතියක්): සම්මත `text` අයිතම
  සරල තන්තු බවටත්, `image` / `audio` / `video` එක් එක් අයිතමය තනි
  `{"content": [part]}` වස්තුවක් බවටත් පත්වේ. මෙහිදී පේළිගත දත්ත සහිත llama-server හි කතාබස් අන්තර්ගත කොටස් (`image_url`,
  `input_audio`, `wav` / `mp3` / `flac` ආකෘතිය සමඟ, `input_video`) භාවිත වේ; එක්
  ඉහළ-මට්ටමේ අයිතමයකට එක් දෛශිකයක්. සේවාදායකය `--embedding --mmproj …` සමඟ ක්රියාත්මක විය යුතුය; ප්රක්ෂේපකයක් නොමැතිව එය
  මාධ්ය ස්වයංක්රීයව ප්රතික්ෂේප කරයි. `document` සඳහා සහාය නොමැත.
- පැහැදිලි මාධ්ය-වර්ග පාරදත්ත නොමැති නොදන්නා/ගතික ආකෘති, HTTP 400 සමඟ ව්යුහගත ආදානය ප්රතික්ෂේප කරයි.

```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 ආපසු ලබා දෙයි. පැරණි තන්තු/token ඉල්ලීම්වල ආදාන නොවන
ව්යාප්ති ක්ෂේත්ර වෙනස් නොවී ඉදිරියට යැවීම දිගටම සිදු වේ.

```bash
# සියලුම embedding ආකෘති ලැයිස්තුගත කරන්න
GET /v1/embeddings
```

---

## රූප උත්පාදනය

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

{
  "model": "openai/gpt-image-2",
  "prompt": "කඳු මතින් දිස්වන සුන්දර හිරු බැස යෑමක්",
  "size": "1024x1024"
}
```

ලබා ගත හැකි සපයන්නන් අතර OpenAI (GPT Image 2), xAI (Grok Image), Together AI (FLUX), Fireworks AI, Nebius (FLUX), Hyperbolic, NanoBanana, **OpenRouter**, **ZenMux**, SD WebUI (දේශීය), ComfyUI (දේශීය) ඇතුළත් වේ.

`n` මඟින් `data[]` තුළ රූප `n`ක් ආපසු ලබා දෙයි. එක් ඇමතුමකට එක් රූපයක් ආපසු ලබා දෙන උඩුගං API සහිත සපයන්නන්
(Black Forest Labs, Stability AI, Leonardo, Ideogram, Haiper, Hyperbolic, Magnific/Freepik,
NVIDIA NIM, Cloudflare Workers AI) සඳහා, එකවර ක්රියාත්මක වන ඇමතුම් සංඛ්යාව උපරිම 4කට සීමා කරමින්, වෙන වෙනම උඩුගං ඇමතුම් `n`ක් සිදු කෙරේ. ස්ථාවර
`seed` අගයක් ඇමතුම් දර්ශකය අනුව (`seed`, `seed + 1`, …) වැඩි කරනු ලබන බැවින්, රූප එකිනෙකට වෙනස් වුවද
නැවත ප්රතිනිෂ්පාදනය කළ හැකිව පවතී. `n` උපරිම 10කට සීමා කර ඇත. කිසියම් ඇමතුමක් අසාර්ථක වුවහොත් සම්පූර්ණ ඉල්ලීමම
අසාර්ථක වේ. විහිදුම් ආකෘති ලැයිස්තුව
`open-sse/handlers/imageGeneration/fanOut.ts` හි `SINGLE_IMAGE_FANOUT_FORMATS` වේ.

ZenMux දැනට පවතින API-යතුරු සම්බන්ධතාව නැවත භාවිත කරන අතර `zenmux/` හෝ `zm/` උපසර්ග පිළිගනී:

- `zenmux/openai/gpt-image-2` ZenMux හි OpenAI Images API භාවිත කරයි. විකල්ප අතර `size`,
  `quality`, `n`, `output_format`, `output_compression`, `background`, සහ `response_format` ඇතුළත් වේ.
- `zm/meta/muse-image-1.0` වැනි අනෙකුත් ප්රකාශකයන් ZenMux හි Vertex AI `:predict`
  අන්ත ලක්ෂ්යය භාවිත කරයි. `n` යන්න `sampleCount` වෙතත්, `aspect_ratio` යන්න `aspectRatio` වෙතත්, `image_size`
  (`1K`, `2K`, `4K`) යන්න `sampleImageSize` වෙතත් සිතියම්ගත වේ. පික්සල් `size` අගයකින් සපයන්නේ දර්ශන අනුපාතයක් පමණක් වන අතර,
  පික්සල් මාන සහතික නොකෙරේ. සහාය දක්වන අනුපාත, විභේදන සහ ගණන් මාදිලිය අනුව වෙනස් වේ.
- `zm/inclusionai/ming-image-0.1-design` තමන්ගේම මාන තෝරා ගනී. `size`,
  `aspect_ratio`, සහ `image_size` ඉවත් කරන්න; පැහැදිලි අගයන් ලබා දීමෙන් HTTP 400 ආපසු ලැබේ. `output_format` සමඟ PNG, JPEG, සහ WebP
  ඉල්ලා සිටිය හැක.

මෙම ඒකාබද්ධ කිරීම පෙළෙන්-රූපයට උත්පාදනයට සහාය දක්වන නමුත්, යොමු-රූප සංස්කරණයට සහාය නොදක්වයි. Vertex
ප්රතිදානය `data[].b64_json` වෙත සාමාන්යකරණය කෙරේ; `response_format: "url"` මඟින් උඩුගං
HTTPS URL එකක් හෝ රූප බයිට් පමණක් ලබා ගත හැකි විට base64 දත්ත URL එකක් ආපසු ලබා දෙයි. හිස්/පෙරහන් කළ ප්රතිදාන
හිස් සාර්ථක ප්රතිචාරයක් වෙනුවට දෝෂයක් ආපසු ලබා දෙයි. මාදිලි ප්රවේශය ZenMux ගිණුම මත රඳා පවතී.
[ZenMux හි Vertex API](https://docs.zenmux.ai/api/vertexai/generate-images) සහ
[OpenAI Images API](https://docs.zenmux.ai/api/openai/generate-an-image) බලන්න.

```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 සපයන්නා තෝරයි; සපයන්නා රහිත model id එකක් (උදා.
`mistral-ocr-latest`) එහි ලියාපදිංචි කළ සපයන්නා වෙත විසඳනු ලබන අතර, `model` අත්හැරියහොත් පෙරනිමියෙන්
Mistral (`mistral-ocr-latest`) භාවිත වේ. ලියාපදිංචි සපයන්නන් (`open-sse/config/ocrRegistry.ts`):

| සපයන්නාගේ id                  | Model id             | `model` අගය                                                         | සටහන්                                                                                                        |
| ----------------------------- | -------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `mistral`                     | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (හෝ සපයන්නා රහිත `mistral-ocr-latest`) | සමමුහුර්තයි — තනි upstream ඇමතුමෙන් ප්රතිචාරය සෘජුවම ආපසු ලබා දේ.                                            |
| `azure-document-intelligence` | `prebuilt-read`      | `azure-document-intelligence/prebuilt-read`                         | අසමමුහුර්ත upstream (`analyze` + poll) — පහත බලන්න.                                                          |
| `vertex-deepseek-ocr`         | `deepseek-ocr-maas`  | `vertex-deepseek-ocr/deepseek-ocr-maas`                             | Vertex AI හි `openapi/chat/completions` හවුල්කාර endpoint එක හරහා සමමුහුර්තයි — සත්යාපනය/URL සඳහා පහත බලන්න. |

සපයන්නන් තිදෙනාම එකම Mistral-හැඩැති body එකකින් ප්රතිචාර දක්වයි:

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

### Azure Document Intelligence poll ප්රවාහය

Azure Document Intelligence හි `analyze` API එක අසමමුහුර්ත වේ: ආරම්භක ඉල්ලීම body එකක් වෙනුවට
`Operation-Location` header එකක් ආපසු ලබා දෙන අතර, ප්රතිඵලය සඳහා වරින් වර විමසිය යුතුය. Handler එක
(`open-sse/handlers/ocr.ts`) උත්සාහ 30ක් දක්වා සෑම තත්පරයකටම එම URL එකෙන් විමසයි, `ok` නොවන poll ප්රතිචාරයකදී හෝ `"failed"` තත්ත්වයකදී වහාම අසාර්ථක වෙයි (දිගටම poll නොකරයි), සහ
උත්සාහ සීමාව අවසන් වූ පසුවත් මෙහෙයුම ක්රියාත්මක වෙමින් පවතී නම් `504` ආපසු ලබා දේ. අවසාන Azure ප්රතිචාරය,
ඇමතුම්කරු වෙත ආපසු ලබා දීමට පෙර Mistral භාවිත කරන එම `pages`/`markdown` හැඩයටම
සාමාන්යකරණය කරනු ලබන බැවින්, client code එකට සපයන්නා සඳහා විශේෂ අවස්ථා හැසිරවීමක් අවශ්ය නොවේ.

### Vertex AI DeepSeek OCR සත්යාපනය සහ endpoint විසඳීම

`vertex-deepseek-ocr`, chat/image ගමනාගමනය සඳහා OmniRoute දැනටමත් සහාය දක්වන
එම Vertex AI සත්යාපනයම නැවත භාවිත කරයි (`open-sse/executors/vertex.ts`): සම්බන්ධතාවයේ API key එක,
JWT-bearer ප්රවාහය හරහා කෙටි කාලීන OAuth access token එකකට හුවමාරු කරන
Service Account JSON අක්තපත්රයක් හෝ, කිසිදු වෙනසකින් තොරව භාවිත කරන දැනටමත් නිකුත් කළ OAuth access token එකක් වේ. Upstream endpoint URL එක යනු සම්බන්ධතාවයේ project සහ
region මත පදනම්ව ගොඩනඟන Vertex හි සාමාන්ය `openapi/chat/completions` හවුල්කාර endpoint එකයි — පැහැදිලි `providerSpecificData.project`/`providerSpecificData.region` අගයක් සැමවිටම ප්රමුඛ වේ;
එසේ නොමැති නම් project එක Service Account JSON හි `project_id` වෙතින් ව්යුත්පන්න කරන අතර region එක
පෙරනිමියෙන් `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 ආකෘතියෙන් සියලුම කතාබස්, embedding සහ රූප ආකෘති + combos ආපසු ලබා දෙයි
```

### ආකෘති id උපසර්ග (`?prefix=`)

බොහෝ ආකෘති **සපයන්නාගේ උපසර්ගයක්** යටතේ ප්රචාරණය කෙරේ. ඔබට ලැබෙන උපසර්ගය
`MODELS_CATALOG_PREFIX_MODE` විශේෂාංග ධජය මඟින් පාලනය වන අතර, query පරාමිතියක් භාවිතයෙන් **එක් එක් ඉල්ලීම සඳහා** එය අභිබවා යා හැක — අනෙක් සියලු දෙනා සඳහා සේවාදායකය පුරා ඇති
සැකසුම වෙනස් නොකර පිරිසිදු ලැයිස්තුවක් අවශ්ය සේවාලාභියෙකුට මෙය ප්රයෝජනවත් වේ:

```bash
GET /v1/models?prefix=alias        # එක් ආකෘතියකට එක් id එකක් — කෙටි alias උපසර්ගය
GET /v1/models?prefix=dual         # ආකාර දෙකම (සේවාදායකයේ පෙරනිමිය)
GET /v1/models?prefix=canonical    # සම්පූර්ණ provider-id උපසර්ගය පමණි
```

| ප්රකාරය     | නිකුත් කරන්නේ                                            | සටහන්                                                                                                                                                                                         |
| ----------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual`      | `cc/claude-sonnet-4-6` **සහ** `claude/claude-sonnet-4-6` | **පෙරනිමිය.** id දෙකම එකම ආකෘතිය වෙත මාර්ගගත වේ; ආකාර දෙකෙන් එකක් ස්ථිරව යොදා ඇති සේවාලාභී වින්යාස දිගටම ක්රියා කිරීමට මෙය තබා ඇත. නාමාවලියේ ප්රමාණය දළ වශයෙන් දෙගුණ කරයි.                    |
| `alias`     | `cc/claude-sonnet-4-6`                                   | එක් ආකෘතියකට එක් ඇතුළත් කිරීමක්. වෙනස් alias එකක් නොමැති සපයන්නන් ද සිය ඇතුළත් කිරීම නිකුත් කරන බැවින් කිසිවක් අහිමි නොවේ.                                                                    |
| `canonical` | `claude/claude-sonnet-4-6`                               | සම්පූර්ණ provider-id උපසර්ගය යටතේ එක් ආකෘතියකට එක් ඇතුළත් කිරීමක්. වෙනස් alias එකක් නොමැති සපයන්නන් (උදා. `antigravity/…`, `agy/…`) ද මෙහි තම තනි id එක නිකුත් කරන බැවින් කිසිවක් අහිමි නොවේ. |

`dual`-ප්රකාරයේ mirror එකක් query පරාමිතිය නොමැතිව ද හඳුනාගත හැක: එහි ප්රධාන id එක වෙත යොමු කරන `parent`
ක්ෂේත්රයක් අඩංගු වේ.

ආකෘති තේරීමේ අංගයක් පෙන්වන සේවාලාභීන් `?prefix=alias` ඉල්ලා සිටිය යුතුය —
[OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) එසේ කරයි.

### තනි තනිව සඟවා ඇති කතාබස් ආකෘති

තම සපයන්නාගේ පිටුවේ **Hidden** ලෙස සලකුණු කර ඇති ආකෘතියක් නාමාවලියෙන් ඉවත් කරනු ලබන අතර, එය පැහැදිලිව ඉල්ලා සිටින විට
HTTP `404` / `model_not_found` සමඟ ප්රතික්ෂේප කෙරේ. මෙම පරීක්ෂාව provider aliases, compatible-provider node prefixes සහ
connection defaults ඇතුළුව resolve කළ සපයන්නා සහ ආකෘතිය භාවිත කරයි. combo එකක් සඟවා ඇති targets මඟහැර දෘශ්ය sibling එකක් භාවිත කළ හැක; ක්රියාත්මක කළ හැකි target එකක් ඉතිරි නොවන විට එය එකම error code එක ආපසු ලබා දෙයි. සැඟවීම ඉවත් කිරීම ඊළඟ
ඉල්ලීමේදී ක්රියාත්මක වේ. රූප සඳහා පමණක් වන දෘශ්යතා overrides, එකම ID එක සහිත කතාබස් ආකෘතිය සඟවන්නේ නැත.

මෙම තනි ආකෘති සැකසුම, පැහැදිලි dispatch රඳවා තබා ගනිමින් නාමාවලි
ප්රචාරණය සහ ස්වයංක්රීය මාර්ගගත කිරීමේ candidates පෙරහන් කරන
[model exposure allow/deny lists](../routing/MODEL_EXPOSURE_LIST.md) වෙතින් වෙන් වූවකි. API-key ආකෘති
අවසර ස්වාධීනව දිගටම අදාළ වේ. පෙරනිමි නාමාවලි උපසර්ග ප්රකාරය `dual` ලෙසම පවතී.

### Thinking නොමැති ආකෘති ප්රභේද

Thinking සඳහා හැකියාව ඇති Claude ආකෘති සඳහා, `/v1/models` මඟින් id එක `claude-3-omniroute-no-thinking/` සමඟ උපසර්ග කළ **no-thinking** ප්රභේදයක් ද ප්රචාරණය කරයි:

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

මෙම id එක තේරීමෙන් (`thinking` block එකක් සැමවිටම අමුණන Claude Code වින්යාසයක වැනි) reasoning අක්රිය කර සැබෑ `<provider>/<model>` වෙත නැවත resolve වේ — `/v1/messages` මාර්ගයේ `thinking:{type:"disabled"}` ලෙස, නැතහොත් `/v1/chat/completions` මාර්ගයේ `reasoning`/`reasoning_effort` ක්ෂේත්ර ඉවත් කරමින්. මෙම ප්රභේදය ලැයිස්තුගත කරන්නේ thinking සඳහා සහාය දක්වන **සහ** `disabled` පිළිගන්නා Claude-family ආකෘති සඳහා පමණි (එබැවින්, උදාහරණයක් ලෙස, `disabled` ප්රතික්ෂේප කරන adaptive-only ආකෘති බැහැර කෙරේ). ක්රියාකරුවන්ට `ModelSpec.noThinkingAlias` හරහා එක් එක් ආකෘතිය සඳහා මෙම ප්රභේදය බලයෙන් සක්රිය හෝ අක්රිය කළ හැක.

---

## සපයන්නා ප්ලගිනයේ මැනිෆෙස්ටය

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

Bifrost, CLIProxyAPI සහ අනාගත sidecar රවුටර භාවිත කරන, JSON-ආරක්ෂිත සපයන්නා ප්ලගිනයේ මැනිෆෙස්ටය ආපසු ලබා දෙයි. ප්රතිචාරය TypeScript සපයන්නා රෙජිස්ට්රියෙන් ජනනය කරන අතර OAuth සේවාදායක රහස්, ධාවනකාල පරිසර විභේදනය, ක්රියාත්මක කිරීමේ ශ්රිත, ඉල්ලීම් ශීර්ෂක සහ ගිණුම් දත්ත හිතාමතාම බැහැර කරයි.

sidecar එකක් ක්රියාවලියෙන් පිටත ධාවනය වන විට සහ
`open-sse/config/providerPluginManifestRegistry.ts` සෘජුවම ආයාත කළ නොහැකි විට මෙම endpoint එක භාවිත කරන්න.

---

## අනුකූලතා අන්ත ලක්ෂ්ය

| ක්රමය | මාර්ගය                                    | ආකෘතිය                                   |
| ----- | ----------------------------------------- | ---------------------------------------- |
| POST  | `/v1/chat/completions`                    | OpenAI                                   |
| POST  | `/v1/messages`                            | Anthropic                                |
| POST  | `/v1/responses`                           | OpenAI Responses                         |
| POST  | `/v1/embeddings`                          | OpenAI                                   |
| POST  | `/v1/images/generations`                  | OpenAI Images                            |
| POST  | `/v1/images/edits`                        | OpenAI Images (සංස්කරණය/inpaint)         |
| POST  | `/v1/videos/generations`                  | OpenAI-ආකාරයේ වීඩියෝ ජනනය                |
| POST  | `/v1/music/generations`                   | OpenAI-ආකාරයේ සංගීත ජනනය                 |
| POST  | `/v1/audio/transcriptions`                | OpenAI Audio (STT)                       |
| POST  | `/v1/audio/speech`                        | OpenAI TTS (ශ්රව්ය body එක ලබා දෙයි)     |
| POST  | `/v1/rerank`                              | Cohere/Voyage-ආකාරයේ නැවත ශ්රේණිගත කිරීම |
| POST  | `/v1/classify`                            | Jina වර්ගීකරණය (`api.jina.ai`)           |
| POST  | `/v1/segment`                             | Jina ඛණ්ඩකය (`segment.jina.ai`)          |
| POST  | `/v1/moderations`                         | OpenAI Moderations                       |
| GET   | `/v1/models`                              | OpenAI                                   |
| POST  | `/v1/messages/count_tokens`               | Anthropic                                |
| GET   | `/v1beta/models`                          | Gemini                                   |
| POST  | `/v1beta/models/{...path}`                | Gemini generateContent                   |
| POST  | `/v1/api/chat`                            | Ollama                                   |
| GET   | `/api/v1/vscode/{token}/`                 | OpenAI නාමාවලි අන්වර්ථය                  |
| GET   | `/api/v1/vscode/{token}/models`           | OpenAI මාදිලි අන්වර්ථය                   |
| POST  | `/api/v1/vscode/{token}/chat/completions` | OpenAI ටෝකනීකෘත අන්වර්ථය                 |
| POST  | `/api/v1/vscode/{token}/responses`        | OpenAI Responses ටෝකනීකෘත අන්වර්ථය       |
| POST  | `/api/v1/vscode/{token}/api/chat`         | Ollama ටෝකනීකෘත අන්වර්ථය                 |
| GET   | `/api/v1/vscode/{token}/api/tags`         | Ollama ටැග් සඳහා ටෝකනීකෘත අන්වර්ථය       |

සියලුම POST මාර්ග එකම ව්යුහය අනුගමනය කරයි: `Bearer your-api-key` + Zod මඟින් වලංගු කළ JSON body එකක් (`v1RerankSchema`, `v1ModerationSchema`, `v1AudioSpeechSchema`, ආදිය; `src/shared/validation/schemas.ts` බලන්න). Schema වලංගුකරණය අසාර්ථක වූ විට 4xx ලබා දෙයි.

`Authorization: Bearer ...` අමුණා යැවිය නොහැකි සේවාලාභීන් සඳහා, OmniRoute විසින් query-string අනුකූලතාව (`?token=...`, `?apiKey=...`, `?api_key=...`, `?key=...`) හෝ පහත ලේඛනගත කර ඇති විශේෂිත `/api/v1/vscode/{token}/...` අන්ත ලක්ෂ්ය හරහා URL එක තුළ API යතුරු ද පිළිගනී.

```bash
# නැවත ශ්රේණිගත කිරීම (වලාකුළු රෙජිස්ට්රි සැපයුම්කරුවෙකු, හෝ "<prefix>/<model>" ලෙස OpenAI-අනුකූල සැපයුම්කරු node එකක්)
POST /v1/rerank      { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }

# Jina වර්ගීකරණය (Foundation API අක්තපත්ර)
POST /v1/classify    { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }

# Jina ඛණ්ඩකය
POST /v1/segment     { "content": "...", "return_chunks": true }

# Jina සෙවීම (s.jina.ai; සැපයුම්කරු අන්වර්ථ: jina-search, jina-ai, jina)
POST /v1/search      { "query": "...", "provider": "jina-search" }

# අන්තර්ගත පාලන
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }

# TTS — audio/mpeg body එකක් (හෝ ඉල්ලා ඇති ආකෘතිය) ලබා දෙයි
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }

# Soniox TTS සඳහා භාෂාවක් සහ හඬක් අවශ්ය වේ: `language` හි පෙරනිමිය "en" වේ; නොමැති
# හඬක් හෝ OpenAI හි සම්මත හඬ නාමයක් (alloy, nova, …) "Adrian" බවට පත් වේ
POST /v1/audio/speech { "model": "soniox/tts-rt-v1", "input": "Xin chào", "voice": "Adrian", "language": "vi" }

# රූප සංස්කරණය (multipart)
POST /v1/images/edits  -F image=@input.png -F prompt="..." -F mask=@mask.png

# වීඩියෝ / සංගීත ජනනය (සැපයුම්කරු උපසර්ගය සහිත මාදිලි හැඳුනුම්කාරකය)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations  { "model": "kie/suno-v4.0",   "prompt": "..." }
```

> **නැවත ශ්රේණිගත කිරීමේ සැපයුම්කරු nodes:** `POST /v1/rerank` මඟින් `<node-prefix>/<model>` ලෙස යොමු කර ඇති OpenAI-අනුකූල සැපයුම්කරු nodes
> (oMLX, vLLM, Infinity, ද්වාරයක් පිටුපස ඇති TEI, …) වෙත ද ඉල්ලීම් මාර්ගගත කරයි. Loopback
> nodes (`localhost`, `127.0.0.1`, `172.16.0.0/12`) සැමවිටම සුදුසුකම් ලබන අතර, ක්රියාකරු
> `OMNIROUTE_LOCAL_PROVIDER_NODE_HOSTS` තුළ ලැයිස්තුගත කරන සත්කාරක නාම ද සුදුසුකම් ලබයි (උදා. `http://reranker:8080/v1` වැනි
> Docker/Compose සේවා නාමයක්; මේවා `HTTP(S)_PROXY` හෝ සම්බන්ධතාවයකට නියම කළ proxy එකක් හරහා කිසිවිටෙක නොයවා
> සෘජුවම අමතනු ලැබේ). වෙනත් ඕනෑම
> සත්කාරකයක ඇති nodes — LAN යන්ත්රයක් හෝ Tailscale සමපාර්ශ්විකයක් — සුදුසුකම් ලබන්නේ ක්රියාකරු
> `RERANK_REMOTE_PROVIDER_NODES` විශේෂාංග ධජය සක්රීය කර ඇති **සහ** node එකේ මූලික URL එක සැපයුම්කරුගේ
> පිටතට යන URL ප්රතිපත්තිය (`OMNIROUTE_ALLOW_LOCAL_PROVIDER_URLS` / `OMNIROUTE_ALLOW_PRIVATE_PROVIDER_URLS`) සමත් වන විට පමණි.
> මතක එන්ජිමේ නැවත ශ්රේණිගත කිරීමේ පියවර මෙම මාර්ගය
> loopback හරහා අමතන බැවින්, Memory සැකසුම් තුළ `rerankProviderModel` සඳහා ද එම රීතියම අදාළ වේ.
>
> **දේශීය සේවාදායක ව්යුහ:** node එක `<base>/v1/rerank` හිදී ද, 404 ලැබුණු විට `<base>/rerank`
> (Infinity, TEI) හිදී ද අමතනු ලැබේ. Upstream body එක තුළ Cohere/OpenAI අක්ෂර වින්යාසය (`documents`,
> `return_documents`) සහ TEI අක්ෂර වින්යාසය (`texts`, `return_text`) යන දෙකම අඩංගු වන අතර, upstream ප්රතිචාරය
> Cohere envelope එකට සාමාන්යකරණය කෙරේ: 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`              | ගොනුවක් උඩුගත කරන්න (multipart: `file`, `purpose`, `expires_after[anchor]`, `expires_after[seconds]`) — උපරිමය 512 MiB |
| GET    | `/v1/files`              | සත්යාපිත API යතුර සඳහා ගොනු ලැයිස්තුගත කරන්න                                                                           |
| GET    | `/v1/files/[id]`         | ගොනුවක පාරදත්ත ලබාගන්න                                                                                                 |
| DELETE | `/v1/files/[id]`         | ගොනුවක් මකන්න                                                                                                          |
| GET    | `/v1/files/[id]/content` | අමු ගොනු අන්තර්ගතය ප්රවාහයක් ලෙස ආපසු ලබාදෙන්න                                                                         |

**සත්යාපනය:** Bearer API යතුර — `getApiKeyRequestScope` හරහා ගොනු එක් එක් API යතුරට සීමා කෙරේ. යතුරකට
දැකිය හැක්කේ, බාගත කළ හැක්කේ සහ මකා දැමිය හැක්කේ එයටම අයත් ගොනු පමණි; යතුරක් නොමැති උපකරණ පුවරු සැසියකට
සම්පූර්ණ අවස්ථාව කියවිය හැක; හිමිකරුවෙකු නොමැති ගොනුවකට (නිර්නාමික හෝ උපකරණ පුවරු සැසි උඩුගත කිරීමක්)
සැසියකින් නොපැමිණෙන සෑම ඇමතුම්කරුවෙකුටම ප්රවේශය ප්රතික්ෂේප කෙරේ. `GET /v1/files` නිර්නාමික ඇමතුම්කරුවෙකු —
සහ ඉදිරිපත් කළ නමුත් නිරාකරණය නොවන යතුරක් — `REQUIRE_API_KEY=false` වන විට පවා, සෑම කුලීකරුවෙකුගේම
ගොනු ලැයිස්තුගත කිරීම වෙනුවට `401` සමඟ ප්රතික්ෂේප කරයි (GHSA-m3hp-hq9g-fpmv, GHSA-2jm2-mpx8-6523).

---

## Batches API

OpenAI-අනුකූල කාණ්ඩ සැකසීම.

| ක්රමය  | මාර්ගය                    | විස්තරය                                                                                                                       |
| ------ | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| POST   | `/v1/batches`             | කාණ්ඩයක් සාදන්න — ඉල්ලීම් අන්තර්ගතය `v1BatchCreateSchema` මඟින් වලංගු කෙරේ (`input_file_id`, `endpoint`, `completion_window`) |
| GET    | `/v1/batches`             | කාණ්ඩ ලැයිස්තුගත කරන්න                                                                                                        |
| GET    | `/v1/batches/[id]`        | කාණ්ඩයේ තත්ත්වය + `request_counts` ලබාගන්න                                                                                    |
| DELETE | `/v1/batches/[id]`        | සම්පූර්ණ වූ/අසාර්ථක වූ කාණ්ඩයක් මකන්න                                                                                         |
| POST   | `/v1/batches/[id]/cancel` | ක්රියාත්මක වෙමින් පවතින කාණ්ඩයක් අවලංගු කරන්න                                                                                 |

**සත්යාපනය:** Bearer API යතුර. ගොනු සඳහා භාවිත වන එම තුන්-ආකාර රීතිය යටතේ කාණ්ඩ එක් එක් API යතුරට සීමා වේ:
තමන්ගේම යතුරට පමණක් ප්රවේශය ඇත, උපකරණ පුවරු සැසියට සමස්ත instance එක පුරා ප්රවේශය ඇත, සහ හිමිකරු-රහිත වාර්තා සඳහා සැසි නොවන සෑම
ඇමතුම්කරුවෙකුටම ප්රවේශය ප්රතික්ෂේප වේ (ලබාගැනීම, මැකීම, අවලංගු කිරීම සහ සෑදීමේදී සිදුකරන `input_file_id` පරීක්ෂාව).
`REQUIRE_API_KEY=false` වූ විට පවා `GET /v1/batches` නිර්නාමික ඇමතුම්කරුවෙකු `401` සමඟ ප්රතික්ෂේප කරයි.

---

## Search API

වෙබ්/සෙවුම් සැපයුම්කරු වියුක්තකරණය (Tavily, Brave, Exa, Serper, ආදිය).

| ක්රමය | මාර්ගය                 | විස්තරය                                                                                                                      |
| ----- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/v1/search`           | වින්යාස කර ඇති සෙවුම් සැපයුම්කරුවන් + හැකියාවන් ලැයිස්තුගත කරන්න                                                             |
| POST  | `/v1/search`           | සෙවුම් විමසුමක් ක්රියාත්මක කරන්න — අන්තර්ගතය `v1SearchSchema` මඟින් වලංගු කෙරේ, හැඹිලිගත කිරීම/ඒකාබද්ධ කිරීම සඳහා සහය දක්වයි |
| GET   | `/v1/search/analytics` | එක් එක් සැපයුම්කරු සඳහා ප්රතිඵල/ප්රමාද/හැඹිලි සංඛ්යාලේඛන                                                                     |

**සත්යාපනය:** Bearer API යතුර (`extractApiKey` + `isValidApiKey`). සෙවුම් ප්රතිපත්තිය `enforceApiKeyPolicy` හරහා බලාත්මක කෙරේ.

---

## Web Fetch API

වින්යාස කළ web-fetch සපයන්නෙකු (Firecrawl, Jina Reader, Tavily Extract, TinyFish Fetch, Nimble Extract) හරහා URL එකකින් අන්තර්ගතය උපුටා ගන්න.

| ක්රමය | මාර්ගය          | විස්තරය                                                                           |
| ----- | --------------- | --------------------------------------------------------------------------------- |
| POST  | `/v1/web/fetch` | URL එකක් ලබාගැනීම/ස්ක්රේප් කිරීම — ඉල්ලීම් බඳ `v1WebFetchSchema` මඟින් වලංගු කෙරේ |

**සත්යාපනය:** Bearer API යතුර (`extractApiKey` + `isValidApiKey`). ප්රතිපත්තිය `enforceApiKeyPolicy` හරහා බලාත්මක කෙරේ.

**කෝටා පිළිබඳ දැනුවත් fallback (#8297):** පැහැදිලි `provider` එකක් ලබා දී නොමැති විට, pool එක
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) ස්ථාවර
ප්රමුඛතා අනුපිළිවෙළකට (fill-first) පරීක්ෂා කෙරේ — ඉල්ලීම වහාම අවසන් කිරීම වෙනුවට,
වින්යාස කර ඇති නමුත් අනුපාත සීමාවකට ලක් වූ සපයන්නෙකු මඟ හරිනු ලබන අතර, නැවත උත්සාහ කළ හැකි/කෝටා සම්බන්ධ upstream අසාර්ථක වීමක්
(HTTP 429 සැමවිටම; Firecrawl/Tavily/TinyFish හි කෝටා ආකාරයේ නොමිලේ මට්ටම් සඳහා 402/403 —
Jina Reader සඳහා නොවන අතර, සාමාන්ය 400 වැරදි ඉල්ලීමක් සඳහා කිසිවිටෙක නොවේ) ඉල්ලීම ක්රියාත්මක වන අවස්ථාවේදී
මීළඟ මෙතෙක් උත්සාහ නොකළ, අක්තපත්ර සහිත සපයන්නා වෙත යොමු වේ. pool එකේ සෑම සපයන්නෙකුම
අවසන් වූ විට, endpoint එක පෙර පැවති සාමාන්ය `400` වෙනුවට තනි `429` එකක්
(`Retry-After` ශීර්ෂයක් සමඟ) ආපසු ලබා දෙයි. පැහැදිලි `provider` එකක් ඉල්ලා ඇති විට,
නිහඬ fallback එකක් **නොමැත** — අනුපාත සීමාවකට ලක් වූ හෝ අසාර්ථක වන පැහැදිලි
සපයන්නාගේම දෝෂය පෙන්වනු ලැබේ (අනුපාත සීමාවකට ලක් වී ඇත්නම් `429`, එසේ නොමැති නම් upstream
තත්ත්වය).

---

## WebSocket ප්රවාහනය

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

WebSocket උත්ශ්රේණිගත කිරීමේ handshake එකක් වලංගු කර wire protocol උදාහරණ පණිවිඩ (`request`, `cancel`) ආපසු ලබා දෙයි. සත්ය WS frames, Next.js මාර්ග වගුවෙන් පිටත ඇති, සමඟ අමුණා ඇති WS server එක මඟින් හසුරුවනු ලැබේ.

**සත්යාපනය:** handshake අතරතුර Bearer API යතුර.

### WebSocket හරහා Responses API (codex පමණි)

```bash
# HTTP API එකට සමාන host:port (පෙරනිමි 20128); සම්බන්ධතාව උත්ශ්රේණිගත කරන්න:
wscat -c "ws://localhost:20128/v1/responses?api_key=<OMNIROUTE_API_KEY>"
# (හෝ: -H "Authorization: Bearer <OMNIROUTE_API_KEY>")

# පළමු frame එක response.create විය යුතුමය:
{ "type": "response.create", "model": "gpt-5.5", "input": [ { "role": "user", "content": "hi" } ] }
```

Responses-API-over-WebSocket proxy එකක් **`codex` වෙත පමණක්** (ChatGPT
backend) සම්බන්ධ කර ඇත. එය API/dashboard එක මෙන්ම එකම port එකේ `/v1/responses`,
`/responses`, සහ `/api/v1/responses` යන මාර්ගවල සවන් දෙයි. පළමු `response.create` frame එකේදී එය
අභ්යන්තර `codex-responses-ws` bridge එක හරහා සත්යාපනය + සූදානම් කිරීම සිදු කර, codex OAuth සම්බන්ධතාවක්
තෝරා, `wreq-js` ප්රවාහනය හරහා `wss://chatgpt.com/backend-api/codex/responses`
වෙත tunnel කරයි. **codex නොවන models ප්රතික්ෂේප කෙරේ** (`codex_ws_provider_required`).
කෝටා-බෙදාගැනීමේ routing සඳහා `model: "qtSd/<group>/codex/<model>"` භාවිත කරන්න. මෙය
`app/server-ws.mjs` + `scripts/dev/responses-ws-proxy.mjs` + `src/app/api/internal/codex-responses-ws/route.ts` තුළ ක්රියාත්මක කර ඇත.

**සත්යාපනය:** handshake අතරතුර Bearer API යතුර. සමඟ අමුණා ඇති HTTP server එක (`server-ws.mjs`)
සක්රිය entrypoint එක විය යුතුය (`app/server-ws.mjs` පවතින විට, පෙරනිමියෙන් එය එසේ වේ).

#### Model id: සරල ChatGPT id එක භාවිත කරන්න (`codex/` උපසර්ගය නොමැතිව)

`supports_websockets = true` වන විට OpenAI **Codex CLI** එක model නාමය client-side හි වලංගු කරන අතර
`codex/gpt-5.5` වැනි **සපයන්නාගේ උපසර්ගය සහිත ids ප්රතික්ෂේප කරයි**
(`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`). **සරල** id එක යවන්න (උදා. `gpt-5.5`). OmniRoute හි bridge එක
codex සඳහා පමණක් වන බැවින්, upstream වෙත tunnel කිරීමට පෙර එය සරල id එකක් codex model එකක් ලෙස
(`resolveCodexWsModelInfo`) නැවත විසඳයි — එම සරල
`gpt-5.5` එක HTTP හරහා වෙනත් සපයන්නෙකු වෙත route විය හැකි වුවද.

#### OpenAI Codex CLI වින්යාස කිරීම

`~/.codex/config.toml` වෙත WebSocket සහාය සහිත අභිරුචි සපයන්නෙකු එක් කිරීමෙන්
Codex CLI එක OmniRoute වෙත යොමු කරන්න (පවතින වින්යාසයකට වෙනස්කම් නොකිරීමට
වෙනම `CODEX_HOME` එකක් භාවිත කරන්න):

```toml
model = "gpt-5.5"                 # සරල id එක — "codex/gpt-5.5" නොවේ
model_provider = "omniroute"

[model_providers.omniroute]
name = "OmniRoute (WS)"
base_url = "http://localhost:20128/v1"   # අවසානයේ slash එකක් නැත; WS URL එක ව්යුත්පන්න කෙරේ (නිෂ්පාදනයේදී https/wss භාවිත කරන්න)
wire_api = "responses"                    # Feb 2026 සිට සහාය දක්වන එකම අගය
supports_websockets = true                # Responses-over-WS ප්රවාහනය සක්රීය කරයි
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 එය
තෝරාගත් codex OAuth සම්බන්ධතාව වෙත tunnel කරයි. දේශීය server එකට එරෙහිව අන්තයේ සිට අන්තය දක්වා
වලංගු කර ඇත: ChatGPT විසින් `codex.rate_limits` + `response.created` ආපසු ලබා දී
සම්පූර්ණ කිරීම ප්රවාහනය කරයි.

---

## කෝටා සහ ගැටලු වාර්තා කිරීම

| ක්රමය | මාර්ගය              | විස්තරය                                                                                               |
| ----- | ------------------- | ----------------------------------------------------------------------------------------------------- |
| GET   | `/v1/quotas/check`  | ලියාපදිංචි යතුරක් නිකුත් කිරීමට පෙර `provider` + `accountId` සඳහා කෝටාව පූර්ව-වලංගු කරන්න             |
| POST  | `/v1/issues/report` | කෝටා/යතුරු නිකුත් කිරීමේ අසාර්ථකත්වයක් GitHub වෙත වාර්තා කරන්න (`GITHUB_ISSUES_REPO` + ටෝකනය අවශ්යයි) |

**සත්යාපනය:** Bearer API යතුර (`isAuthenticated`).

---

## ස්වයං-සේවා භාවිතය (`/api/usage/om-usage`)

ඕනෑම API යතුරකට **තමන්ගේම** භාවිතය සහ කෝටා කියවිය හැක — කළමනාකරණ සත්යාපනය අවශ්ය නොවේ. යතුරු හිමියෙකුට තම වියදම පෙන්වීම සඳහා client එකක් (CLI, OmniCopilot පැනලය) භාවිත කරන endpoint එක මෙයයි.

```bash
# පෙළ ආකෘතිය (ඓතිහාසික ගිවිසුම — terminal එකක් සඳහා සාමාන්ය පෙළ)
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`** සක්රීය කර තිබිය යුතුය (පෙරනිමියෙන් අක්රීයයි — dashboard එකේ API-key කළමනාකරු එය එක් එක් යතුර සඳහා මාරු කරයි). එය නොමැතිව endpoint එක `403` ලෙස ප්රතිචාර දක්වයි.

ප්රතික්ෂේප කිරීමකදී caller කෙනෙකු දත්ත ක්ෂේත්රයක් කිසිවිටෙක කියවන්නේ නැති පරිදි `?format=json` විසින් වෙනස්කම් හඳුනාගත හැකි ව්යුහයක් ආපසු ලබා දෙයි. සාර්ථක වූ විට:

```jsonc
{
  "allowed": true,
  // යතුර එක් යතුරකට අදාළ භාවිත සීමා (දෛනික/සතිපතා USD) සඳහා තේරීම සිදු කර ඇති විට පමණක් පවතී:
  "personal": {
    "dailySpentUsd": 1.25,
    "dailyLimitUsd": 5,
    "dailyResetAtIso": "…",
    "weeklySpentUsd": 8,
    "weeklyLimitUsd": 20,
    "weeklyResetAtIso": "…" /* … */,
  },
  // තෝරාගත් provider කෝටා snapshot එක, හෝ තවම කිසිවක් cache කර නොමැති විට null:
  "provider": {
    "connectionId": "…",
    "provider": "claude",
    "plan": "…",
    "quotas": {/* … */},
  },
  // UI එකකට provider කිහිපයක් එකිනෙකට යාබදව render කළ හැකි වන පරිදි, සෑම connection එකකම snapshot එක:
  "providers": [
    { "connectionId": "…", "provider": "claude" /* … */ },
    { "provider": "codex" /* … */ },
  ],
}
```

ප්රතික්ෂේප කිරීමකදී (`401` වැරදි යතුර / `403` අවසර නැත) එම route එකම
`{ "allowed": false, "error": { "message": "…" } }` ආපසු ලබා දෙයි — පවතින නමුත් හිස් `personal`/`provider`
(යතුරට අවසර ඇත, තවම කිසිවක් දැනගෙන නැත) යනු ප්රතික්ෂේප කිරීමකට වඩා වෙනස් තත්ත්වයක් වන අතර, ඒවා වෙන්කර හඳුනාගන්නේ JSON ආකෘතිය පමණි.

**සත්යාපනය:** caller ගේම Bearer API යතුර, `isValidApiKey` සමඟ වලංගු කරනු ලැබේ — මෙය
`requireManagementAuth` පසුපස පවතින කළමනාකරණ පෘෂ්ඨය (`/api/keys/…`) _නොවේ_.

### අමු හා Cutoff-සීරුමාරු කළ කෝටා ප්රතිශත

`/api/usage/om-usage` පරිභෝජනය කරන විට, **සාමාන්ය පෙළ ප්රතිදානය** සහ ව්යුහගත **JSON ප්රතිදානය** මඟින් ඉදිරිපත් කරන ප්රතිශත අතර වෙනස caller විසින් සැලකිල්ලට ගත යුතුය:

| අංශය                   | සාමාන්ය පෙළ ආකෘතිය (`/api/usage/om-usage` / `@@om-usage`)                                  | JSON ආකෘතිය (`?format=json`)                                                      |
| :--------------------- | :----------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------- |
| **ප්රතිදාන ක්ෂේත්රය**  | `NN% left` (උදා., `20% left`)                                                              | `provider.quotas` / `providers[].quotas`                                          |
| **මිනුම**              | **Cutoff-සීරුමාරු කළ භාවිත කළ හැකි දීමනාව**: cutoff සීමාවට ඉහළින් ඉතිරි ධාරිතාව            | **අමු upstream කෝටාව**: සීරුමාරු නොකළ provider මිනුම                              |
| **Cutoff පරිමාණනය**    | ආරක්ෂිත සංචිතය `0% left` ලෙස කියවෙන පරිදි `effectiveRemainingPercent()` හරහා පරිමාණනය කරයි | කිසිවක් නැත (provider විසින් වාර්තා කළ පරිදි අමු snapshot අගයන්)                  |
| **සීමා දත්ත**          | පෙන්වන ප්රතිශතයට ඇතුළත් කර ඇත                                                              | එක් එක් connection එකට `quotaWindowThresholds` තුළ ගබඩා කර ඇත (හෝ server පෙරනිමි) |
| **ප්රධාන පාරිභෝගිකයා** | අන්තර්ක්රියාකාරී CLI, terminal prompt, මානව ක්රියාකරුවන්                                   | ක්රමලේඛනමය ඒකාබද්ධ කිරීම්, dashboard, විශ්ලේෂණ, බිල්පත් ලුහුබැඳීම්                |

#### Cutoff සීරුමාරු කිරීමේ සූත්රය

upstream සම්පත් අවසන් වීම වැළැක්වීම සඳහා OmniRoute ක්රියාකාරී කෝටා cutoff සඳහා සහාය දක්වයි (connection
`quotaWindowThresholds`, provider පෙරනිමි, හෝ ගෝලීය resilience සැකසුම් හරහා වින්යාස කෙරේ). කෝටා කවුළුවක cutoff සීමාවක්
(උදා., `cutoff = 25%`) සක්රීය වූ විට, පෙළ renderer එක ඉතිරි දීමනාව පහත පරිදි ගණනය කරයි:

- `remaining <= cutoff` නම්: `0%` ආපසු ලබා දෙයි.
- `remaining > cutoff` නම්: `((remaining - cutoff) / (100 - cutoff)) * 100` ආපසු ලබා දෙයි.

ආකෘතිගත පෙළ ප්රතිදානය මෙය ආසන්නතම පූර්ණ සංඛ්යාවට වටයයි (`Math.round(...)`).

#### නිදර්ශනාත්මක උදාහරණය

**60% අමු භාවිතයක්** (එබැවින් **40% අමු ඉතිරි කෝටාවක්**) සහ වින්යාස කළ
**25% ඉතිරි-කෝටා cutoff** සීමාවක් සහිත provider කවුළුවක් සලකා බලන්න:

| නිරූපණය                       | ගණනය                                               | ඉතිරිය  |                  අනුමාන භාවිතය                  |
| :---------------------------- | :------------------------------------------------- | :-----: | :---------------------------------------------: |
| **අමු JSON (`?format=json`)** | Upstream snapshot (`quotas[window]`)               | **40%** |                     **60%**                     |
| **පෙළ ආකෘතිය (`NN% left`)**   | `((40 - 25) / (100 - 25)) * 100 = (15 / 75) * 100` | **20%** | **80%** (`100 - remaining` ලෙස ගණනය කරන්නේ නම්) |

- **පෙළෙහි 20% ඉතිරි බව පෙන්වන්නේ ඇයි:** ගිණුමේ භෞතිකව ඉතිරිව ඇති 40% කෝටාවෙන්, 25% ක්
  cutoff ප්රතිපත්තිය මඟින් සංචිත කර ඇත. router එක මෙම connection එක වෙත routing කිරීම නවත්වන්නට පෙර,
  භාවිත කළ හැකි 75% headroom එකෙන් caller ට ඉතිරිව ඇත්තේ 15% ක් පමණි. routing නතර වන මොහොතේම
  connection එක සම්පත් අවසන් වීම (`0% left`) සංඥා කරන බව පරිමාණනය සහතික කරයි.
- **JSON අමු අගයන් සුරකින්නේ ඇයි:** බාහිර මෙවලම්වලට සත්ය upstream භාවිතය සහ connection මට්ටමේ
  `quotaWindowThresholds` වෙත ප්රවේශය ලබා දීම සඳහා JSON payload එක නිශ්චිත provider snapshot එක (`UsageSnapshot`)
  ආපසු ලබා දෙයි; server පාර්ශ්වයේ දත්ත අහිමි කරන පරිමාණනයක් සිදු නොකරයි.

#### පාරිභෝගික සංක්රමණ මාර්ගෝපදේශය

බාහිර ඒකාබද්ධ කිරීමක් (editor plugin එකක් හෝ agent extension එකක් වැනි) මීට පෙර පෙළ
endpoint එකෙන් (`NN% left`) දත්ත උපුටාගෙන භාවිත කළ ප්රතිශතය `100 - NN` ලෙස ගණනය කළේ නම්, `?format=json` වෙත සංක්රමණය වීමේ අර්ථය වන්නේ:

- අමු JSON අගයන් කියවීමෙන් **සැබෑ upstream පරිභෝජනය** පිළිබිඹු වේ (ඉහත උදාහරණයේ භාවිතය 60% කි).
- ඒකාබද්ධ කිරීම පෙළ endpoint එකේ භාවිත කළ හැකි-දීමනා අර්ථය සුරැකීමට කැමති නම්, connection මට්ටමේ overrides සඳහා `quotaWindowThresholds` භාවිත කරමින් effective remaining සූත්රය client පාර්ශ්වයේ ඇගයිය හැක.

---

## අර්ථකථන හැඹිලිය

```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` ප්රතිචාර ශීර්ෂය පරීක්ෂා කළ යුතුය:

| අගය         | අර්ථය                                                      |
| ----------- | ---------------------------------------------------------- |
| `synthetic` | ප්රතිචාරය හැඹිලියෙන් සපයා ඇත; ප්රමාදය සැබෑ උඩුගං කාලය නොවේ |
| _(නොමැත)_   | සැබෑ උඩුගං ඇමතුමකින් ලැබුණු ප්රතිචාරය                      |

### එක්-යතුරකට හැඹිලිය මඟහැරීම

API යතුරුවලට `cacheDefaultMode` හරහා අර්ථකථන හැඹිලි කියවීම්වලින් ඉවත් විය හැකිය:

| අගය      | හැසිරීම                                                    |
| -------- | ---------------------------------------------------------- |
| `legacy` | සාමාන්ය හැඹිලි හැසිරීම (පෙරනිමිය)                          |
| `bypass` | හැඹිලි සෙවීම සම්පූර්ණයෙන් මඟහරින්න; සැමවිටම උඩුගං වෙත යන්න |

යතුර නිර්මාණය කිරීමේදී (`POST /api/keys`) සකසන්න, නැතහොත් (`PATCH /api/keys/[id]`) යාවත්කාලීන කරන්න:

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

### එක්-ඉල්ලීමකට මඟහැරීම

යතුරු සැකසුම් නොසලකා ඕනෑම ඉල්ලීමකට හැඹිලිය මඟහැරිය හැකිය:

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

---

## උපකරණ පුවරුව සහ කළමනාකරණය

කළමනාකරණ මාර්ග (`/api/*`, පොදු auth/login හැර) සාමාන්ය inference 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                   | සැපයුම්කරු node කළමනාකරණය                                                                                                                               |
| `/api/provider-models`                  | GET/POST/PUT/PATCH/DELETE | අභිරුචි ආකෘති සහ එක් එක් ආකෘතියට අදාළ අතික්රමණ (එක් කිරීම, යාවත්කාලීන කිරීම, සැඟවීම/පෙන්වීම, මකා දැමීම)                                                 |
| `/api/provider-models/validate-and-add` | POST                      | කළමනාකරණ-සත්යාපිත, තෝරා සක්රිය කළ දැඩි සම්බන්ධතා වලංගුකරණය සහ පරමාණුක අභිරුචි-ආකෘති ලියාපදිංචිය; [ආකෘති වලංගුකරණය](../guides/MODEL-VALIDATION.md) බලන්න |

සමමුහුර්ත කළ/ආයාත කළ ආකෘති සඳහා, `PUT /api/provider-models` විසින් `provider`, `modelId`, සහ
`maxOutputTokenOverride` පිළිගනී: ධන නිඛිලයක් අතින් නියම කරන output-token සීමාව සකසන අතර, `null`
මඟින් පෙරනිමිය ප්රතිස්ථාපනය කිරීම සඳහා එය ඉවත් කරයි. `GET /api/provider-models?provider=<provider>` විසින් අභිරුචි-ආකෘති පේළියක් නොමැති ආකෘතිද ඇතුළුව, මෙම
අගයන් `modelOutputOverrides` තුළ ආපසු ලබා දෙයි. අතික්රමණය runtime `max_output_tokens` හැකියාව
භාවිත කරන අතර ආකෘතියක් නැවත සමමුහුර්ත කළද පවතී. OpenAI-අනුකූල සැපයුම්කරු පිටුවේ එම සංස්කරණ/ඉවත් කිරීමේ
පාලකම පිරිනමන අතර පැහැදිලි vision සහාය සහිත ආකෘති සලකුණු කරයි.

අභිරුචි Chat Completions node, පැහැදිලි reasoning ඉවත් කිරීම් upstream backend එකට ගැළපෙන ලෙස සකසයි.
සාර්ථක සම්බන්ධතා පරීක්ෂණයක්, `/models` ප්රවේශය හඳුනාගත් `owned_by` අගයක් වන `vllm`, `sglang`, හෝ `llamacpp`
තහවුරු කරන සෑම නිශ්චිත model ID එකක් සඳහාම chat-template පාලක ස්වයංක්රීයව තෝරයි.
පාරදෘශ්ය OpenAI-අනුකූල wrapper මඟින් මුල් ආකෘති ප්රවේශය nested `openai` object එකක් තුළ තබාගත හැක;
හඳුනාගැනීම එවැනි envelope තුනක් දක්වා අනුගමනය කරයි. හිමිකාරීත්වය අස්ථානගත, නොදන්නා හෝ
ගැටුම්කාරී ආකෘති සාමාන්ය OpenAI හැසිරීම තබාගනී. හඳුනාගැනීම පවතින catalog ඉල්ලීම නැවත භාවිත කරයි,
completion token කිසිවක් ජනනය නොකරයි, සහ සම්බන්ධතා අන්ත ලක්ෂ්යය වෙනස් වූ විට අවලංගු වේ.

එම metadata නිරාවරණය නොකරන backend එකක් සඳහා හැසිරීම ස්ථාවර කිරීමට, පවතින අර්ධ
සැපයුම්කරු යාවත්කාලීන API එක භාවිත කරන්න:

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

එම body එක `PUT /api/providers/<connection-id>` සමඟ යවන්න. එම සම්බන්ධතාවයේදී, `none` ලෙස දක්වා ඇති
පැහැදිලි reasoning effort එකක් `chat_template_kwargs.thinking=false` සහ
`chat_template_kwargs.enable_thinking=false` ලෙස යවනු ලැබේ. server-side reasoning රීතියක් මඟින් effort එකක් බලහත්කාරයෙන් නියම නොකරන්නේ නම්,
පැහැදිලි native template අගයන්ට ප්රමුඛත්වය හිමි වේ. මෙම සැකසුම අදාළ වන්නේ අභිරුචි
OpenAI-අනුකූල සම්බන්ධතාවක් Chat Completions body එකක් යවන විට පමණි; Responses ඉල්ලීම් සහ සාමාන්ය
සැපයුම්කරුවන් ඔවුන්ගේ native ඉල්ලීම් ව්යුහය තබාගනී. සාමාන්ය OpenAI `reasoning_effort` passthrough එක
බලහත්කාරයෙන් යෙදීමට `reasoningControl` එක `openai` ලෙස සකසන්න, නැතහොත් ස්වයංක්රීය හඳුනාගැනීම භාවිත කිරීමට එය අත්හරින්න/`null` ලෙස සකසන්න.

පැහැදිලි තර්කන පාලන කිසිවක් අඩංගු නොවන Claude Code auto-mode classifier ඉල්ලීම් සඳහා පෙරනිමි native thinking අක්රිය කරනු ලැබේ. අනාවරණය කිරීම සඳහා භාවිත කරන්නේ model නම් හෝ completion සීමා නොව, Claude-format ඉල්ලීම් තුළ ඇති classifier හි system marker එකයි. පැහැදිලි body පාලන, සහාය දක්වන effort/thinking headers, routing රීති සහ විසඳන ලද model effort සඳහා ඒවායේ පවතින ප්රමුඛතාව එලෙසම පවතී. classifier අදියර දෙකම ඒවායේ prompts, completion සීමා, stop sequences සහ සැබෑ upstream permission තීන්දු රඳවා ගනී; දෙවන අදියරට තවමත් එය ඉල්ලා සිටි දෘශ්ය තර්කනය සාමාන්ය පෙළ ලෙස නිපදවිය හැක.

### OAuth ප්රවාහ

| Endpoint                         | ක්රමය | විස්තරය                |
| -------------------------------- | ----- | ---------------------- |
| `/api/oauth/[provider]/[action]` | විවිධ | Provider-විශේෂිත OAuth |

### Routing සහ වින්යාසය

| Endpoint              | ක්රමය    | විස්තරය                            |
| --------------------- | -------- | ---------------------------------- |
| `/api/models/alias`   | GET/POST | Model අන්වර්ථ නාම                  |
| `/api/models/catalog` | GET      | Provider + වර්ගය අනුව සියලු models |
| `/api/combos*`        | විවිධ    | Combo කළමනාකරණය                    |
| `/api/keys*`          | විවිධ    | API key කළමනාකරණය                  |
| `/api/pricing`        | GET      | Model මිලකරණය                      |

### භාවිතය සහ විශ්ලේෂණ

| Endpoint                         | ක්රමය           | විස්තරය                                                                                                                                                                                                                                                                                                         |
| -------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/usage/history`             | GET             | භාවිත ඉතිහාසය                                                                                                                                                                                                                                                                                                   |
| `/api/usage/logs`                | GET             | භාවිත logs                                                                                                                                                                                                                                                                                                      |
| `/api/usage/request-logs`        | GET             | ඉල්ලීම් මට්ටමේ logs                                                                                                                                                                                                                                                                                             |
| `/api/usage/[connectionId]`      | GET             | එක් එක් connection සඳහා භාවිතය                                                                                                                                                                                                                                                                                  |
| `/api/usage/token-limits`        | GET/POST/DELETE | එක් එක් API key සඳහා token-limit අයවැය                                                                                                                                                                                                                                                                          |
| `/api/usage/model-latency-stats` | GET             | එක් එක් provider/model සඳහා අඛණ්ඩ latency සමස්තය (avg/p50/p95/p99, සාර්ථකත්ව අනුපාතය); filters: `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873)                                                                                                                                                 |
| `/api/usage/cache-health`        | GET             | `call_logs` මත පදනම් වූ prompt-cache සෞඛ්ය සාරාංශය — write/read අනුපාතය, p50/p90/p99 write-size ව්යාප්තිය, heavy-write සාන්ද්රණය, එක් එක් model සඳහා වෙන් කිරීම සහ `healthy`/`degraded`/`thrash`/`no-data` තීන්දුවක්; query params `range` (`1h`\|`24h`\|`7d`\|`30d`, පෙරනිමිය `24h`) සහ විකල්ප `model` (#8827) |

### API key අවසර

`PATCH /api/keys/{id}` මඟින් පවතින key එකක අවසර යාවත්කාලීන කරයි. සෑම `/api/keys*` route එකක් මෙන්ම, මෙයට inference key එකක් නොව management authorization අවශ්ය වේ ([Management Authentication](../guides/MANAGEMENT-AUTH.md) බලන්න). ඔබට වෙනස් කිරීමට අවශ්ය fields පමණක් යවන්න; ඒවායින් එකක්වත් නොමැති ඉල්ලීමක් `No valid fields to update` සමඟ ප්රතික්ෂේප වේ. පිළිගන්නා fields `src/shared/validation/schemas/keys.ts` තුළ ඇති `updateKeyPermissionsSchema` මඟින් අර්ථ දක්වා ඇත.

| ක්ෂේත්රය                                    | වර්ගය                                                              | සටහන්                                                                                                                       |
| ------------------------------------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------- |
| `name`                                      | තන්තුවක්, අක්ෂර 1-200                                              |                                                                                                                             |
| `isActive`                                  | බූලියානු අගයක්                                                     |                                                                                                                             |
| `isBanned`                                  | බූලියානු අගයක්                                                     |                                                                                                                             |
| `expiresAt`                                 | ISO 8601 දින-වේලාවක් හෝ `null`                                     | `null` මඟින් කල් ඉකුත්වීම ඉවත් කරයි                                                                                         |
| `modelAccessMode`                           | `all` \| `restricted`                                              | ප්රකාරය `all` වන විට `allowedModels` හිස් විය යුතුය                                                                         |
| `allowedModels`, `blockedModels`            | තන්තු අරාවක්, උපරිම 1000ක්                                         |                                                                                                                             |
| `allowedCombos`                             | තන්තු අරාවක්, උපරිම 500ක්                                          | යතුරට ඇමතිය හැකි combos පාලනය කරයි; සෘජු models `modelAccessMode` / `allowedModels` මඟින් පාලනය වේ                          |
| `connectionAccessMode`                      | `all` \| `restricted`                                              | `restricted` වන විට `allowedConnections` හිස් නොවිය යුතු අතර `all` වන විට හිස් විය යුතුය                                    |
| `allowedConnections`                        | UUID අරාවක්, උපරිම 100ක්                                           |                                                                                                                             |
| `allowAutoCombos`                           | බූලියානු අගයක්                                                     | `false` නම් මෙම යතුර සමඟ `auto/*` models සඳහා වන ඉල්ලීම් ප්රතික්ෂේප කරයි; මෙය කිසිදා සකසා නොමැති යතුරුවලට අවසර ඇත           |
| `catalogScope`                              | `all` \| `combos` \| `models`                                      | මෙම යතුර සඳහා `GET /v1/models` ලැයිස්තුගත කරන දෑ (combos පමණක්, models පමණක්, හෝ දෙකම); එය යතුරට ඇමතිය හැකි දෑ වෙනස් නොකරයි |
| `noLog`, `autoResolve`                      | බූලියානු අගයක්                                                     |                                                                                                                             |
| `throttleDelayMs`                           | පූර්ණ සංඛ්යාවක්, 0-300000                                          |                                                                                                                             |
| `maxSessions`                               | පූර්ණ සංඛ්යාවක්, 0-10000                                           |                                                                                                                             |
| `rateLimits`                                | `{ limit, window }` අරාවක් (ධන පූර්ණ සංඛ්යා, උපරිම 50ක්) හෝ `null` | `null` මඟින් සීමා ඉවත් කරයි                                                                                                 |
| `accessSchedule`                            | කාලසටහන් වස්තුවක් හෝ `null`                                        | `null` මඟින් කාලසටහන ඉවත් කරයි                                                                                              |
| `scopes`                                    | තන්තු අරාවක්, උපරිම 32ක්                                           |                                                                                                                             |
| `allowedEndpoints`                          | තන්තු අරාවක්, උපරිම 20ක්                                           |                                                                                                                             |
| `streamDefaultMode`                         | `legacy` \| `json`                                                 |                                                                                                                             |
| `cacheDefaultMode`                          | `legacy` \| `bypass`                                               | [යතුරකට අදාළ cache මඟහැරීම](#per-key-cache-bypass) බලන්න                                                                    |
| `compressionEnabled`                        | බූලියානු අගයක්                                                     |                                                                                                                             |
| `codexServiceMode`                          | Codex සේවා ප්රකාරවලින් එකක්                                        |                                                                                                                             |
| `disableNonPublicModels`                    | බූලියානු අගයක්                                                     |                                                                                                                             |
| `allowUsageCommand`                         | boolean                                                            |                                                                                                                             |
| `usageLimitEnabled`                         | boolean                                                            |                                                                                                                             |
| `dailyUsageLimitUsd`, `weeklyUsageLimitUsd` | 0 හෝ ඊට වැඩි number එකක් හෝ `null`                                 |                                                                                                                             |
| `chaosModeEnabled`                          | boolean                                                            |                                                                                                                             |

```bash
curl -X PATCH "$OMNIROUTE_URL/api/keys/$KEY_ID" \
  -H "Authorization: Bearer <management-credential>" \
  -H "Content-Type: application/json" \
  -d '{ "allowAutoCombos": false, "catalogScope": "combos" }'
```

### සැකසුම්

| අන්ත ලක්ෂ්යය                          | ක්රමය         | විස්තරය                                                                                                                                                                              |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/settings`                       | GET/PUT/PATCH | සාමාන්ය සැකසුම්                                                                                                                                                                      |
| `/api/settings/proxy`                 | GET/PUT       | ජාල ප්රොක්සි වින්යාසය                                                                                                                                                                |
| `/api/settings/proxy/test`            | POST          | ප්රොක්සි සම්බන්ධතාව පරීක්ෂා කිරීම                                                                                                                                                    |
| `/api/settings/ip-filter`             | GET/PUT       | IP අවසර ලැයිස්තුව/අවහිර ලැයිස්තුව                                                                                                                                                    |
| `/api/settings/thinking-budget`       | GET/PUT       | සිතීමේ/තර්ක කිරීමේ **ඉල්ලීම්** නැවත ලිවීමේ ප්රකාරය (passthrough / auto-strip / custom / adaptive). සම්පීඩනයෙන් ස්වාධීන වේ. [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           | off/lite/standard/aggressive/ultra/RTK/stacked සම්පීඩනය පෙරදසුන් කිරීම |
| `/api/compression/language-packs`      | GET            | ලබා ගත හැකි Caveman භාෂා ඇසුරුම් ලැයිස්තුගත කිරීම                      |
| `/api/compression/rules`               | GET            | Caveman රීති පාරදත්ත ලැයිස්තුගත කිරීම                                  |
| `/api/context/caveman/config`          | GET/PUT        | Caveman-විශේෂිත සැකසුම් අන්වර්ථය                                       |
| `/api/context/rtk/config`              | GET/PUT        | අභිරුචි පෙරහන් සහ අමු ප්රතිදාන රඳවාගැනීම ඇතුළුව RTK-විශේෂිත සැකසුම්    |
| `/api/context/rtk/filters`             | GET            | RTK පෙරහන් නාමාවලිය සහ අභිරුචි-පෙරහන් රෝගනිශ්චය                        |
| `/api/context/rtk/test`                | POST           | පෙළ පේලෝඩයකට එරෙහිව RTK පෙරදසුන/පරීක්ෂණය ධාවනය කිරීම                   |
| `/api/context/rtk/raw-output/[id]`     | GET            | දර්ශක id අනුව රඳවාගත් සංස්කරණය කළ අමු ප්රතිදානය කියවීම                 |
| `/api/context/combos`                  | GET/POST       | සම්පීඩන සංයෝජන ලැයිස්තුගත කිරීම/නිර්මාණය කිරීම                         |
| `/api/context/combos/[id]`             | GET/PUT/DELETE | සම්පීඩන සංයෝජනයේ විස්තර/යාවත්කාලීන කිරීම/මකා දැමීම                     |
| `/api/context/combos/[id]/assignments` | GET/PUT        | සම්පීඩන සංයෝජන මාර්ගගත කිරීමේ සංයෝජන වෙත පැවරීම                        |
| `/api/context/analytics`               | GET            | සම්පීඩන විශ්ලේෂණ අන්වර්ථය                                              |

### අධීක්ෂණය

| Endpoint                             | Method     | විස්තරය                                                                                                                                                                                                                                                                                                                                                                                            |
| ------------------------------------ | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions`                      | GET        | සක්රිය සැසි ලුහුබැඳීම                                                                                                                                                                                                                                                                                                                                                                              |
| `/api/rate-limits`                   | GET        | එක් එක් ගිණුම සඳහා අනුපාත සීමා                                                                                                                                                                                                                                                                                                                                                                     |
| `/api/monitoring/health`             | GET        | සෞඛ්ය පරීක්ෂාව + සපයන්නන්ගේ සාරාංශය (`catalogCount`, `configuredCount`, `activeCount`, `monitoredCount`). කළමනාකරණ දසුනට `credentialHealth` ඇතුළත් වේ: probe-cache අදිශ අගයන්, `failed>0` වන විට `failedConnections`, සහ `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        | කළමනාකරණ සත්යාපනයට/probe කිරීමට පෙර දැඩි විශ්වාසදායක-loopback පරීක්ෂාව; පිරිසිදු කළ FFmpeg/ffprobe ලබාගත හැකි බව සහ අනුවාද (ගබඩා නොකෙරේ)                                                                                                                                                                                                                                                           |
| `/api/modality-bridge/video/extract` | POST       | අභ්යන්තර සත්යාපිත විශ්වාසදායක-loopback බයිට් තැරැව්කරු; 50 MiB ආදානය, සීමා කළ පෝලිම/32 MiB ප්රතිදානය, ධාරිතාව සඳහා `503`, විසන්ධි වීම සඳහා `499`, කාලසීමාව ඉක්මවීම සඳහා `504`; මෙය පොදු උඩුගත කිරීමේ API එකක් නොවේ                                                                                                                                                                                 |

### උපස්ථ කිරීම සහ නිර්යාතය/ආයාතය

| Endpoint                    | Method | විස්තරය                                                                                                   |
| --------------------------- | ------ | --------------------------------------------------------------------------------------------------------- |
| `/api/db-backups`           | GET    | ලබාගත හැකි උපස්ථ ලැයිස්තුගත කිරීම                                                                         |
| `/api/db-backups`           | PUT    | අතින් උපස්ථයක් සෑදීම                                                                                      |
| `/api/db-backups`           | POST   | නිශ්චිත උපස්ථයකින් ප්රතිසාධනය කිරීම                                                                       |
| `/api/db-backups/export`    | GET    | දත්ත සමුදාය .sqlite ගොනුවක් ලෙස බාගැනීම                                                                   |
| `/api/db-backups/import`    | POST   | දත්ත සමුදාය ප්රතිස්ථාපනය කිරීමට .sqlite ගොනුවක් උඩුගත කිරීම (`?dryRun=true` වලංගුභාවය පමණක් පරීක්ෂා කරයි) |
| `/api/db-backups/exportAll` | GET    | සම්පූර්ණ උපස්ථය .tar.gz සංරක්ෂිතයක් ලෙස බාගැනීම                                                           |

`/api/db-backups/export`, `/api/db-backups/exportAll` සහ `/api/settings/export-json` මඟින්
ගබඩා කර ඇති සෑම අක්තපත්රයක්ම ලබා දෙන බැවින්, ඒවාට උපකරණ පුවරු සැසිය හෝ දේශීය CLI අවශ්ය වේ (නැතහොත් පිවිසුම
අක්රිය කර තිබිය යුතුය). ඕනෑම විෂය පථයක API යතුරු සහ `oma_` ප්රවේශ ටෝකනවලට `403` ලැබේ.

`/api/db-backups/export`, `/api/db-backups/exportAll` and `/api/settings/export-json` hand out
every stored credential, so they require the dashboard session or the local CLI (or login
disabled). API keys of any scope and `oma_` access tokens get `403`. The restores hold the same
boundary: `POST /api/db-backups/import` (`dryRun=true` included), `POST /api/db-backups` (restore
by id) and `POST /api/settings/import-json` replace the live database or settings, so a machine
credential gets `403` there too; `omniroute sync import` sends the local CLI credential.

### වලාකුළු සමමුහුර්තකරණය

| Endpoint               | Method  | විස්තරය                           |
| ---------------------- | ------- | --------------------------------- |
| `/api/sync/cloud`      | Various | වලාකුළු සමමුහුර්ත කිරීමේ මෙහෙයුම් |
| `/api/sync/initialize` | POST    | සමමුහුර්ත කිරීම ආරම්භ කිරීම       |
| `/api/cloud/*`         | Various | වලාකුළු කළමනාකරණය                 |

### උමං මාර්ග

| Endpoint                   | Method | විස්තරය                                                              |
| -------------------------- | ------ | -------------------------------------------------------------------- |
| `/api/tunnels/cloudflared` | GET    | උපකරණ පුවරුව සඳහා Cloudflare Quick Tunnel ස්ථාපන/ධාවන තත්ත්වය කියවීම |
| `/api/tunnels/cloudflared` | POST   | Cloudflare Quick Tunnel සබල හෝ අබල කිරීම (`action=enable/disable`)   |
| `/api/tunnels/ngrok`       | GET    | උපකරණ පුවරුව සඳහා ngrok Tunnel ධාවන තත්ත්වය කියවීම                   |
| `/api/tunnels/ngrok`       | POST   | ngrok Tunnel සබල හෝ අබල කිරීම (`action=enable/disable`)              |

### CLI මෙවලම්

| Endpoint                           | Method | විස්තරය                 |
| ---------------------------------- | ------ | ----------------------- |
| `/api/cli-tools/claude-settings`   | GET    | Claude CLI තත්ත්වය      |
| `/api/cli-tools/codex-settings`    | GET    | Codex CLI තත්ත්වය       |
| `/api/cli-tools/droid-settings`    | GET    | Droid CLI තත්ත්වය       |
| `/api/cli-tools/openclaw-settings` | GET    | OpenClaw CLI තත්ත්වය    |
| `/api/cli-tools/runtime/[toolId]`  | GET    | සාමාන්ය CLI ධාවන පරිසරය |

CLI ප්රතිචාරවල ඇතුළත් වන්නේ: `installed`, `runnable`, `command`, `commandPath`, `runtimeMode`, `reason`.

### ACP නියෝජිතයන්

| Endpoint          | Method | විස්තරය                                                                       |
| ----------------- | ------ | ----------------------------------------------------------------------------- |
| `/api/acp/agents` | GET    | තත්ත්වය සමඟ හඳුනාගත් සියලු නියෝජිතයන් (බිල්ට්-ඉන් + අභිරුචි) ලැයිස්තුගත කිරීම |
| `/api/acp/agents` | POST   | අභිරුචි නියෝජිතයෙකු එක් කිරීම හෝ හඳුනාගැනීමේ හැඹිලිය නැවුම් කිරීම             |
| `/api/acp/agents` | DELETE | `id` විමසුම් පරාමිතිය අනුව අභිරුචි නියෝජිතයෙකු ඉවත් කිරීම                     |

GET ප්රතිචාරයට `agents[]` (id, name, binary, version, installed, protocol, isCustom) සහ `summary` (total, installed, notFound, builtIn, custom) ඇතුළත් වේ.

### ප්රත්යස්ථතාව සහ අනුපාත සීමා

| Endpoint                          | Method    | විස්තරය                                                                                                     |
| --------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------- |
| `/api/resilience`                 | GET/PATCH | ඉල්ලීම් පෝලිම, සම්බන්ධතා විරාමය, සපයන්නාගේ පරිපථ බිඳුම සහ රැඳී සිටීමේ සැකසුම් ලබාගැනීම/යාවත්කාලීන කිරීම     |
| `/api/resilience/reset`           | POST      | සපයන්නාගේ පරිපථ බිඳුම් යළි සැකසීම                                                                           |
| `/api/resilience/model-cooldowns` | GET       | ඉතිරි කාලය අනුව අනුපිළිවෙළට සකසා ඇති සක්රිය එක්-(සපයන්නා, සම්බන්ධතාව, ආකෘතිය) අගුලු දැමීම් ලැයිස්තුගත කිරීම |
| `/api/resilience/model-cooldowns` | DELETE    | ආකෘති අගුලු දැමීමක් ඉවත් කිරීම — body `{provider, model}` හෝ සියල්ල මකා දැමීමට `{all: true}`                |
| `/api/rate-limits`                | GET       | එක් එක් ගිණුම සඳහා අනුපාත සීමා තත්ත්වය                                                                      |
| `/api/rate-limit`                 | GET       | ගෝලීය අනුපාත සීමා වින්යාසය                                                                                  |

> `/api/resilience/*` මාර්ග හතරටම **කළමනාකරණ සත්යාපනය** (`requireManagementAuth`) අවශ්ය වේ. සපයන්නාගේ පරිපථ බිඳුම, සම්බන්ධතා විරාමය සහ ආකෘති අගුලු දැමීම අතර වෙනස පිළිබඳ සම්පූර්ණ විස්තරයක් සඳහා [ප්රත්යස්ථතාව (විස්තීර්ණ)](#resilience-extended) බලන්න.

### ඇගයීම්

| Endpoint     | Method   | විස්තරය                                             |
| ------------ | -------- | --------------------------------------------------- |
| `/api/evals` | GET/POST | ඇගයීම් කට්ටල ලැයිස්තුගත කිරීම / ඇගයීමක් ධාවනය කිරීම |

### ප්රතිපත්ති

| Endpoint        | Method          | විස්තරය                                   |
| --------------- | --------------- | ----------------------------------------- |
| `/api/policies` | GET/POST/DELETE | මාර්ගගත කිරීමේ ප්රතිපත්ති කළමනාකරණය කිරීම |

### අනුකූලතාව

| Endpoint                    | Method | විස්තරය                       |
| --------------------------- | ------ | ----------------------------- |
| `/api/compliance/audit-log` | GET    | අනුකූලතා විගණන ලොගය (අවසන් N) |

### v1beta (Gemini-අනුකූල)

| Endpoint                   | Method | විස්තරය                                 |
| -------------------------- | ------ | --------------------------------------- |
| `/v1beta/models`           | GET    | Gemini ආකෘතියෙන් ආකෘති ලැයිස්තුගත කිරීම |
| `/v1beta/models/{...path}` | POST   | Gemini `generateContent` endpoint       |

දේශීය Gemini SDK අනුකූලතාව අපේක්ෂා කරන සේවාලාභීන් සඳහා මෙම endpoint, Gemini API ආකෘතිය පිළිබිඹු කරයි.

### අභ්යන්තර / පද්ධති API

| Endpoint                 | Method | විස්තරය                                                       |
| ------------------------ | ------ | ------------------------------------------------------------- |
| `/api/init`              | GET    | යෙදුම් ආරම්භකරණ පරීක්ෂාව (පළමු ධාවනයේදී භාවිත වේ)             |
| `/api/tags`              | GET    | Ollama-අනුකූල ආකෘති ටැග් (Ollama සේවාලාභීන් සඳහා)             |
| `/api/restart`           | POST   | ක්රමානුකූල සේවාදායක යළි ආරම්භයක් ක්රියාත්මක කිරීම             |
| `/api/shutdown`          | POST   | ක්රමානුකූල සේවාදායක වසා දැමීමක් ක්රියාත්මක කිරීම              |
| `/api/system/env/repair` | POST   | OAuth සපයන්නාගේ පරිසර විචල්ය අලුත්වැඩියා කිරීම                |
| `/api/system/version`    | GET    | වත්මන්/නවතම අනුවාදය, යාවත්කාලීන තත්ත්වය, නිකුතු නාලිකාව       |
| `/api/system/version`    | POST   | නවතම අනුවාදයට යෙදවීම පිළිබඳ දැනුවත් යාවත්කාලීනයක් ආරම්භ කිරීම |

> **සටහන:** මෙම endpoint පද්ධතිය විසින් අභ්යන්තරව හෝ Ollama සේවාලාභී අනුකූලතාව සඳහා භාවිත කරයි. සාමාන්යයෙන් අවසාන පරිශීලකයන් විසින් ඒවා කැඳවනු නොලැබේ.

### 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
GET /api/system/version
```

Loopback සඳහා පමණක් වන කළමනාකරණ මාර්ගය (පරිපාලක සත්යාපනය). දැනට ක්රියාත්මක වන අනුවාදය, නවතම
ප්රකාශිත අනුවාදය සහ ස්වයංක්රීය යාවත්කාලීන තත්ත්වය ආපසු ලබා දෙයි. `releaseChannel` සහ `channels` යනු අතිරේක
ක්ෂේත්ර වේ (rail 3.8.54); `channel` එහි අර්ථය දිගටම පවත්වා ගනී — dashboard යාවත්කාලීනකාරකය
භාවිත කරන යෙදවීම් ආකාරය (`npm`, `source` හෝ `docker-compose`).

```json
{
  "current": "3.8.52",
  "latest": "3.8.52",
  "updateAvailable": false,
  "channel": "npm",
  "autoUpdateSupported": true,
  "autoUpdateError": null,
  "news": null,
  "releaseChannel": "latest",
  "channels": { "latest": "3.8.52", "next": "3.8.53-rc.1" }
}
```

- `releaseChannel` — ක්රියාත්මක වන build එකේ npm නාලිකාව: `-nightly.*` අනුවාද සඳහා `nightly`,
  අනෙකුත් පූර්ව නිකුතු සඳහා (`-rc.*`, `-beta.*`, `-alpha.*`) `next`, `channels.latest` ට වඩා පැරණි
  ප්රධාන අනුවාදයක ස්ථාවර අනුවාදයක් සඳහා `lts`, එසේ නොමැති නම් `latest`. ප්රකාශන අවස්ථාවේදී
  npm dist-tag තෝරාගන්නා `scripts/release/dist-tag.mjs` හි නීතිම වේ.
- `channels` — `npm view omniroute dist-tags` වෙතින් ලැබෙන එක් එක් dist-tag හි නවතම ප්රකාශිත අනුවාදය (registry
  HTTP fallback සමඟ), `latest` සඳහා භාවිත කරන මිනිත්තු 10ක TTL එකම භාවිත කරමින් cache කර ඇත. `latest` සැමවිටම පවතී
  (පළමුව `latest` ක්ෂේත්රය වෙතත්, පසුව `"unavailable"` වෙතත් fallback වේ); `next`, `nightly` සහ `lts`
  පෙන්වන්නේ අදාළ dist-tag පවතින විට පමණි. `Cache-Control: no-cache` ඉල්ලීමක් lookup දෙකම නැවුම් කරයි.

නාලිකා ආකෘතිය (`latest` = 4.0 GA දක්වා v3, `next` = rc, `nightly` = `develop` builds,
`lts` = 4.0 GA පසු v3 patches) `docs/ops/RELEASE_STRATEGY.md` හි විස්තර කර ඇත.

---

## ශ්රව්ය පිටපත් කිරීම

```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 අනුකූලතාව

Ollama හි API ආකෘතිය භාවිත කරන සේවාලාභීන් සඳහා:

```bash
# කතාබස් අන්ත ලක්ෂ්යය (Ollama ආකෘතිය)
POST /v1/api/chat

# ආකෘති ලැයිස්තුගත කිරීම (Ollama ආකෘතිය)
GET /api/tags
```

ඉල්ලීම් Ollama සහ අභ්යන්තර ආකෘති අතර ස්වයංක්රීයව පරිවර්තනය කෙරේ.

## ටෝකනීකරණය කළ VS Code / ශීර්ෂ රහිත අන්වර්ථ නාම

ඒකාබද්ධ කිරීමකට `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

# Ollama-ශෛලියේ අන්වර්ථ නාම
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`) අවශ්ය වේ. `scopeType` එක `global` නොවේ නම් `scopeValue` අවශ්ය වේ (උදා. `model` විෂය පථයක් සඳහා model id එකක්, `provider` විෂය පථයක් සඳහා provider id එකක්). `tokenLimit` ධන පූර්ණ සංඛ්යාවක් විය යුතුය (තන්තුවකින් පරිවර්තනය කෙරේ). විකල්ප: `id` (සෑදීමට අත්හරින්න, යාවත්කාලීන කිරීමට සපයන්න), `resetInterval` (`daily` | `weekly` | `monthly`, පෙරනිමිය `monthly`), `resetTime` (`HH:MM`), `enabled` (පෙරනිමිය `true`). `GET` ප්රතිචාර මඟින් සෑම සීමාවකටම `tokensUsed`, `remaining`, `windowStart`, `periodStartAt`, සහ `nextResetAt` එක් කර වැඩිදියුණු කෙරේ. මෙය කළමනාකරණ-පන්තියේ අන්ත ලක්ෂ්යයකි (authz නළ මාර්ගය මඟින් සත්යාපනය මධ්යගතව බලාත්මක කෙරේ).

## ඉල්ලීම් සැකසීම

1. සේවාලාභියා `/v1/*` වෙත ඉල්ලීමක් යවයි
2. මාර්ග හසුරුවනය `handleChat`, `handleEmbedding`, `handleAudioTranscription`, හෝ `handleImageGeneration` කැඳවයි
3. ආකෘතිය නිරාකරණය කෙරේ (සෘජු provider/model හෝ alias/combo)
4. ගිණුම් ලබාගත හැකි බව පෙරහන් කර, දේශීය DB එකෙන් අක්තපත්ර තෝරාගනු ලැබේ
5. chat සඳහා: `handleChatCore` අර්ථාර්ථ/අත්සන් cache පරීක්ෂා කර combo සම්පීඩන සැකසුම් නිරාකරණය කරයි
6. සබල කර ඇති විට, provider පරිවර්තනයට පෙර ප්රාක්ක්රියාකාරී සම්පීඩනය ක්රියාත්මක වේ (`lite`, Caveman, RTK, හෝ ස්තරගත)
7. Provider executor ඉහළ ප්රවාහ ඉල්ලීම යවයි
8. ප්රතිචාරය නැවත සේවාලාභී ආකෘතියට පරිවර්තනය කෙරේ (chat), නැතහොත් තිබෙන ආකාරයෙන්ම ආපසු ලබා දේ (embeddings/images/audio)
9. භාවිතය, සම්පීඩන විශ්ලේෂණ, සහ ඉල්ලීම් ලොග් සටහන් කරනු ලැබේ
10. දෝෂ ඇති විට combo නීති අනුව fallback යෙදේ

සම්පූර්ණ නිර්මාණ ශිල්ප යොමුව: [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)

---

## Combo කළමනාකරණය

ඉහළ-මට්ටමේ මාර්ගගත කිරීමේ combos (`/api/combos*` යටතේ දැනටමත් සාරාංශගත කර ඇත) model id රටාවකින් 1:1 ලෙසද සිතියම්ගත කළ හැකි අතර, එමඟින් OpenAI-ශෛලියේ model id එකක් combo එකකට විනිවිද පෙනෙන ලෙස යළි යොමු කිරීමට ඉඩ සලසයි.

| ක්රමය  | මාර්ගය                           | විස්තරය                                                                                  |
| ------ | -------------------------------- | ---------------------------------------------------------------------------------------- |
| GET    | `/api/model-combo-mappings`      | සියලුම model→combo සිතියම්ගත කිරීම් ලැයිස්තුගත කරන්න                                     |
| POST   | `/api/model-combo-mappings`      | සිතියම්ගත කිරීමක් සාදන්න — body: `{pattern, comboId, priority?, enabled?, description?}` |
| GET    | `/api/model-combo-mappings/[id]` | තනි සිතියම්ගත කිරීමක් ලබාගන්න                                                            |
| PUT    | `/api/model-combo-mappings/[id]` | පවතින සිතියම්ගත කිරීමක ක්ෂේත්ර යාවත්කාලීන කරන්න                                          |
| DELETE | `/api/model-combo-mappings/[id]` | සිතියම්ගත කිරීමක් ඉවත් කරන්න                                                             |

**සත්යාපනය:** කළමනාකරණ session/API යතුර (`requireManagementAuth`).

---

## Webhooks

OmniRoute සිදුවීම් සඳහා පිටතට යැවෙන webhook දායකත්ව (ඉල්ලීම් සම්පූර්ණ වීම, quota අවසන් වීම, යතුරු මාරු කිරීම ආදිය).

| ක්රමය  | මාර්ගය                    | විස්තරය                                                                   |
| ------ | ------------------------- | ------------------------------------------------------------------------- |
| GET    | `/api/webhooks`           | webhooks ලැයිස්තුගත කරයි (රහස් `<prefix>...` ලෙස සඟවා පෙන්වයි)            |
| POST   | `/api/webhooks`           | webhook එකක් සාදයි — body: `{url, events?: ["*"], secret?, description?}` |
| GET    | `/api/webhooks/[id]`      | webhook එකක් ලබා ගනියි                                                    |
| PUT    | `/api/webhooks/[id]`      | url/events/secret/description යාවත්කාලීන කරයි                             |
| DELETE | `/api/webhooks/[id]`      | webhook එකක් ඉවත් කරයි                                                    |
| POST   | `/api/webhooks/[id]/test` | webhook URL වෙත පරීක්ෂණ payload එකක් යවා බෙදාහැරීමේ තත්ත්වය ආපසු ලබා දෙයි |

**සත්යාපනය:** කළමනාකරණ සැසිය/API යතුර (`requireManagementAuth`).

---

## ලියාපදිංචි කළ යතුරු (ස්වයංක්රීය කළමනාකරණය)

දෛනික/පැයකට අදාළ කෝටා සහිතව, පසුබිම් සැපයුම්කරුවෙකුට/ගිණුමකට එරෙහිව API යතුරු නිකුත් කිරීමට සහ මාරු කිරීමට ස්වයංක්රීය යතුරු කළමනාකරණ උපපද්ධතිය විසින් භාවිත කරයි.

| ක්රමය  | මාර්ගය                                | විස්තරය                                                                                                                                                                                                                                 |
| ------ | ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/registered-keys`             | ලියාපදිංචි කළ යතුරු ලැයිස්තුගත කරයි (ආවරණය කළ උපසර්ගය පමණි)                                                                                                                                                                             |
| POST   | `/api/v1/registered-keys`             | නව ලියාපදිංචි කළ යතුරක් නිකුත් කරයි — body: `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`. අමු යතුර **එක් වරක්** පමණක් ආපසු ලබා දෙයි. කෝටාව හේතුවෙන් ප්රතික්ෂේප කළහොත් `429` ආපසු ලබා දෙයි. |
| GET    | `/api/v1/registered-keys/[id]`        | ලියාපදිංචි කළ යතුරක පාරදත්ත ලබා ගනී (අමු දත්ත නොමැතිව)                                                                                                                                                                                  |
| DELETE | `/api/v1/registered-keys/[id]`        | ලියාපදිංචි කළ යතුරක් අවලංගු කරයි                                                                                                                                                                                                        |
| POST   | `/api/v1/registered-keys/[id]/revoke` | පැහැදිලි අවලංගු කිරීමේ අන්ත ලක්ෂ්යය (DELETE හා සමාන බලපෑමක් ඇත)                                                                                                                                                                         |

**සත්යාපනය:** කළමනාකරණ සැසිය/API යතුර (`requireManagementAuth`) — `/api/keys` සඳහා භාවිත කරන ආරක්ෂකයම වේ: උපකරණ පුවරු සැසියක්, දේශීය CLI ටෝකනය, හෝ `manage`/`admin` විෂයපථය සහිත API යතුරක්; අනුමානය සඳහා පමණක් වන API යතුරුවලට `403` ලැබේ. `/v1/quotas/check` සහ `/v1/issues/report` ද බලන්න.

---

## Agents ප්රොටෝකෝලය

OmniRoute පරිශීලකයන් වෙනුවෙන් දුරස්ථව ක්රියාත්මක කරන cloud agent කාර්යයන් (Claude Code, Codex Cloud, OpenHands, ආදිය).

| ක්රමය  | මාර්ගය                        | විස්තරය                                                                                                                                                          |
| ------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/agents/tasks`        | කාර්යයන් ලැයිස්තුගත කරයි — විකල්ප `?provider=`, `?status=`, `?limit=` (1–500, පෙරනිමිය 50)                                                                       |
| POST   | `/api/v1/agents/tasks`        | කාර්යයක් සාදයි — body එක `CreateCloudAgentTaskSchema` මඟින් වලංගු කෙරේ (`providerId`, `prompt`, `source`, `options?`). කාර්ය envelope එක සමඟ `201` ආපසු ලබා දෙයි |
| DELETE | `/api/v1/agents/tasks?id=...` | කාර්යයක් මකයි                                                                                                                                                    |
| GET    | `/api/v1/agents/tasks/[id]`   | කාර්යය කියවයි — `external_id` සකසා ඇති විට upstream cloud agent වෙතින් තත්ත්වය සමමුහුර්තව නැවුම් කරයි                                                            |
| POST   | `/api/v1/agents/tasks/[id]`   | වෙනස්කම් අනුව හඳුනාගන්නා ක්රියාව: `{action: "approve"}`, `{action: "message", message}`, හෝ `{action: "cancel"}`                                                 |
| DELETE | `/api/v1/agents/tasks/[id]`   | id අනුව නිශ්චිත කාර්යයක් මකයි                                                                                                                                    |

> **සත්යාපනය:** සෑම ක්රමයක් සඳහාම management සත්යාපනය අවශ්ය වේ (`requireCloudAgentManagementAuth`). v3.8.0 ට පෙර මේවා සත්යාපනය නොකළ ඒවා විය — පසුගාමී නොගැළපෙන වෙනස සඳහා `588a0333` commit එක බලන්න.

```bash
# Claude Code cloud කාර්යයක් සාදන්න
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":"..."}}'
```

---

## Management ප්රොක්සි

providers, accounts වෙත හෝ ගෝලීයව පැවරිය හැකි පිටතට යන HTTP(S)/SOCKS ප්රොක්සි.

| ක්රමය  | මාර්ගය                                       | විස්තරය                                                                                                                                                               |
| ------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/v1/management/proxies`                 | ප්රොක්සි ලැයිස්තුගත කරයි (`?id=` සමඟ එකක් ආපසු ලබා දෙයි; `?id=&where_used=1` සමඟ පැවරුම් ප්රස්තාරය ආපසු ලබා දෙයි)                                                     |
| POST   | `/api/v1/management/proxies`                 | ප්රොක්සියක් සාදයි — body එක `createProxyRegistrySchema` මඟින් වලංගු කෙරේ                                                                                              |
| PATCH  | `/api/v1/management/proxies`                 | ප්රොක්සිය යාවත්කාලීන කරයි — body එක `updateProxyRegistrySchema` මඟින් වලංගු කෙරේ (`id` අවශ්යයි)                                                                       |
| DELETE | `/api/v1/management/proxies?id=...&force=1`  | ප්රොක්සිය මකයි (පැවරුම් ඉවත් කිරීමට `force=1` භාවිත කරන්න)                                                                                                            |
| GET    | `/api/v1/management/proxies/assignments`     | පැවරුම් ලැයිස්තුගත කරයි — `proxy_id`, `scope`, `scope_id` මඟින් පෙරහන් කළ හැකිය; connection එකක් සඳහා සක්රිය ප්රොක්සිය විසඳීමට `resolve_connection_id=<id>` ලබා දෙන්න |
| PUT    | `/api/v1/management/proxies/assignments`     | පවරයි — body එක `proxyAssignmentSchema` මඟින් වලංගු කෙරේ (`{scope, scopeId?, proxyId?}`). dispatcher cache එක හිස් කරයි                                               |
| PUT    | `/api/v1/management/proxies/bulk-assign`     | තොග වශයෙන් පවරයි — body එක `bulkProxyAssignmentSchema` මඟින් වලංගු කෙරේ (`{scope, scopeIds[], proxyId?}`)                                                             |
| GET    | `/api/v1/management/proxies/health?hours=24` | කාල පරාසයක් තුළ සමස්ත ප්රොක්සි සෞඛ්යය (සාර්ථක/අසාර්ථක ගණන්, ප්රමාදය)                                                                                                  |

**සත්යාපනය:** සෑම route එකක් සඳහාම management session/API key එකක් අවශ්ය වේ (`requireManagementAuth`).

> කාර්ය විස්තරයේ ඇති `POST /api/v1/management/proxies/[id]/assignments` සහ `POST /api/v1/management/proxies/[id]/health`, ඉහත පෙන්වා ඇති පැතලි `/assignments` සහ `/health` routes මඟින් සපයනු ලැබේ — codebase එකේ එක් එක් id සඳහා වෙනම subroutes නොමැත.

---

## ප්රත්යස්ථතාව (විස්තීර්ණ)

OmniRoute ස්වාධීන තාවකාලික-අසාර්ථකත්ව යාන්ත්රණ තුනක් නිරාවරණය කරයි; පහත කළමනාකරණ අන්ත ලක්ෂ්ය මඟින් ක්රියාකරුවන්ට ඒවා කියවීමට සහ අතික්රමණය කිරීමට හැකියාව ලැබේ:

| විෂය පථය                | තත්ත්ව ගබඩාව                               | කියවීම                                    | යළි පිහිටුවීම / හිස් කිරීම                                    |
| ----------------------- | ------------------------------------------ | ----------------------------------------- | ------------------------------------------------------------- |
| සැපයුම්කරු පරිපථ බිඳිනය | `domain_circuit_breakers` + මතකය තුළ       | `/api/monitoring/health`                  | `POST /api/resilience/reset`                                  |
| සම්බන්ධතා විරාම කාලය    | සැපයුම්කරු සම්බන්ධතා මත `rateLimitedUntil` | `/api/rate-limits`, `/api/providers/[id]` | (අවශ්ය වූ විට නැවත සක්රීය වේ; සැපයුම්කරු PUT හරහා හිස් කරන්න) |
| ආකෘති අගුළු දැමීම       | මතකය තුළ ඇති ආකෘති-ලබාගතහැකිතා රෙජිස්ට්රිය | `GET /api/resilience/model-cooldowns`     | `DELETE /api/resilience/model-cooldowns`                      |

`PATCH /api/resilience` විසින් `providerBreaker.oauth` සහ `providerBreaker.apikey` යටතේ සැපයුම්කරු පරිපථ බිඳින අතික්රමණ පිළිගනී. සෑම පැතිකඩක්ම `degradationThreshold`, `failureThreshold`, සහ `resetTimeoutMs` සඳහා සහාය දක්වයි; එම ක්ෂේත්රම Dashboard → Settings → Resilience තුළද ලබා දී ඇත.

```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) → "ප්රත්යස්ථතා ධාවනකාල තත්ත්වය" බලන්න.

---

## කුසලතා

අභිරුචි ක්රියාත්මක කළ හැකි හසුරුවන්නන් සහ වෙළඳපොළ ඒකාබද්ධ කිරීම් මඟින් 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 මඟින් වලංගු කරන ලද body: `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET    | `/api/memory/[id]`   | එක් මතකයක් ලබාගැනීම                                                                                                        |
| DELETE | `/api/memory/[id]`   | මතකයක් මකා දැමීම                                                                                                           |
| GET    | `/api/memory/health` | මතක උපපද්ධතියේ සෞඛ්ය තත්ත්වය (DB සම්බන්ධතාව, embeddings backend, vector index තත්ත්වය)                                     |

**සත්යාපනය:** කළමනාකරණ සැසිය/API යතුර (`requireManagementAuth`). `type` enum: `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts` තුළ ඇති `MemoryType` බලන්න).

---

## MCP සේවාදායකය

OmniRoute විෂය පථගත මෙවලම් සහ transports 3ක් (stdio, SSE, streamable-http) සහිත අන්තර්ගත Model Context Protocol සේවාදායකයක් සපයයි. පහත dashboard endpoints තත්ත්ව/විගණන දත්ත කියවා HTTP transports proxy කරයි.

| ක්රමය | මාර්ගය | විස්තරය |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | Heartbeat, transport, online තත්ත්වය, අවසන් ඇමතුම, ප්රමුඛ මෙවලම්, පැය 24ක සාර්ථකත්ව අනුපාතය |
| GET | `/api/mcp/tools` | `name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` සහිත MCP මෙවලම් ලැයිස්තුව |
| GET | `/api/mcp/sse` | SSE transport සඳහා SSE stream එකක් විවෘත කිරීම (MCP අක්රිය නම් හෝ transport නොගැළපේ නම් `503` ආපසු ලබාදෙයි) |
| POST | `/api/mcp/sse` | SSE transport මත JSON-RPC frame එකක් යැවීම |
| GET | `/api/mcp/stream` | Streamable HTTP transport හි SSE පාර්ශ්වය විවෘත කිරීම (සේවාදායකය විසින් ආරම්භ කරන පණිවිඩ) |
| POST | `/api/mcp/stream` | Streamable HTTP transport මත JSON-RPC frame එකක් යැවීම |
| DELETE | `/api/mcp/stream` | Streamable HTTP සැසියක් අවසන් කිරීම |
| GET | `/api/mcp/audit` | විගණන ලොගය විමසීම — `?limit=`, `?offset=`, `?tool=`, `?success=true                                | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | සමස්ත විගණන සංඛ්යාලේඛන (එකතු, සාර්ථකත්ව අනුපාතය, සාමාන්ය කාලසීමාව, ප්රමුඛ මෙවලම්) |

**සත්යාපනය:** `sse`/`stream` transports MCP-විශේෂිත සත්යාපන මතුපිටට අනුකූල වේ (`mcp` scope සහිත Bearer API යතුර); `status`/`tools`/`audit*` මාර්ග dashboard වෙතින් කියවිය හැකිය (dashboard host වෙත ළඟා වීමට අවශ්ය ප්රවේශයට අමතර සත්යාපනයක් අවශ්ය නොවේ).

> HTTP transports දෙකම `settings.mcpEnabled` සහ `settings.mcpTransport` මඟින් පාලනය වේ — transport නොගැළපීමක් `400` ආපසු ලබාදෙන අතර, MCP අක්රිය තත්ත්වයක් `503` ආපසු ලබාදෙයි.

---

## A2A සේවාදායකය

OmniRoute විසින් A2A (Agent-to-Agent) 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 නියෝජිත කාඩ්පත (නම, විස්තරය, හැකියාවන්, කුසලතා නාමාවලිය, සත්යාපන යෝජනා ක්රමය) ආපසු ලබා දෙයි — පැය 1ක් සඳහා පොදුවේ හැඹිලිගත කෙරේ. සත්යාපනය අවශ්ය නොවේ.

### 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` | තක්සේරුවක් ධාවනය කරන්න — body: `{scope: {type:"all"}                                                   | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | අන්තර්ගත eval කට්ටල සහ වඩාත් මෑත ධාවන ලැයිස්තුගත කරන්න |
| POST | `/api/evals` | eval ධාවනයක් ආරම්භ කරන්න |
| POST | `/api/evals/suites` | අභිරුචි eval කට්ටලයක් සාදන්න — body එක `evalSuiteSaveSchema` මඟින් වලංගු කෙරේ |
| GET | `/api/evals/suites/[id]` | අභිරුචි eval කට්ටලයක් ලබා ගන්න |

**සත්යාපනය:** `/api/cloud/auth` විසින් Bearer යතුරක් සෘජුවම වලංගු කර, `manage` / `admin` විෂය පථය සහිත යතුරක් සඳහා පමණක් එක් එක් සම්බන්ධතාවේ ආවරණය කළ යතුර සහ `projectId` ආපසු ලබා දෙයි; අනෙකුත් `/api/cloud/*`, `/api/evals/*`, සහ `/api/assess` මාර්ග සඳහා කළමනාකරණ සැසියක්/API යතුරක් අවශ්ය වේ. `/api/assess` POST විසින් වෙනස්කම් හඳුනාගත හැකි union විෂය පථ schema එකක් සමඟ `validateBody` භාවිත කරයි.

---

## ACP (Agent Client Protocol) කළමනාකරණය

ළමා ක්රියාවලි ලෙස. මෙම අන්ත ලක්ෂ්ය ACP නියෝජිත හඳුනාගැනීම සහ අභිරුචි නියෝජිත
ලියාපදිංචිය කළමනාකරණය කරයි.

| ක්රමය  | මාර්ගය            | විස්තරය                                                                                                                                                                                 |
| ------ | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/acp/agents` | ස්ථාපන තත්ත්වය, අනුවාදය සහ ද්විමය ගොනුව සමඟ දන්නා සියලුම CLI නියෝජිතයන් (අන්තර්ගත + අභිරුචි) ලැයිස්තුගත කරයි                                                                            |
| POST   | `/api/acp/agents` | අභිරුචි ACP නියෝජිතයෙකු ලියාපදිංචි කිරීම හෝ හැඹිලිය නැවුම් කිරීම — ඉල්ලීම් අන්තර්ගතය: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` හෝ `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | අභිරුචි ACP නියෝජිතයෙකු ඉවත් කරයි — විමසුම් පරාමිතිය: `?id=<agentId>`                                                                                                                   |

**ප්රතිචාර උදාහරණය** (`GET /api/acp/agents`):

```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 රාමුව](../frameworks/ACP.md) බලන්න.

---

## විශ්ලේෂණ සහ නිරීක්ෂණ හැකියාව

මාර්ගගත කිරීම, සම්පීඩනය සහ සැපයුම්කරුවන්ගේ විවිධත්වය අධීක්ෂණය කිරීම සඳහා තත්ය කාලීන විශ්ලේෂණ අන්ත ලක්ෂ්ය.
මේවා `/dashboard/analytics/*` පිටු බලගන්වයි.

### ස්වයංක්රීය මාර්ගගත කිරීමේ විශ්ලේෂණ

| ක්රමය | මාර්ගය                               | විස්තරය                                                                                                            |
| ----- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| GET   | `/api/analytics/auto-routing`        | සමස්ත ස්වයංක්රීය මාර්ගගත කිරීමේ සංඛ්යාලේඛන: මුළු ඇමතුම්, උපායමාර්ග ව්යාප්තිය, ස්ථර ව්යාප්තිය, ප්රමුඛ සැපයුම්කරුවන් |
| GET   | `/api/analytics/auto-routing?days=7` | කාල කවුළුවකට සීමා කළ සංඛ්යාලේඛන (පෙරනිමිය පැය 24කි)                                                                |

**ප්රතිචාර උදාහරණය**:

```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` | Shannon එන්ට්රොපිය මත පදනම් වූ විවිධත්ව නිරීක්ෂණය: සැපයුම්කරුවන්ගේ ව්යාප්තිය මැනීමෙන් තනි අසාර්ථක ස්ථාන ඇතිවීම වළක්වයි |

**ප්රතිචාර උදාහරණය**:

```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 යතුරක් අවශ්ය වේ.

---

## පරිපාලක මෙහෙයුම්

මෙහෙයුම් කළමනාකරණය සඳහා පරිපාලකයින්ට පමණක් සීමා වූ අන්ත ලක්ෂ්ය.

| ක්රමය | මාර්ගය                   | විස්තරය                                                                                                       |
| ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/admin/concurrency` | වත්මන් සමගාමීතා සීමා කියවන්න (ගෝලීය + එක් එක් සපයන්නා අනුව)                                                   |
| POST  | `/api/admin/concurrency` | සමගාමීතා සීමා යාවත්කාලීන කරන්න — ඉල්ලීම් අන්තර්ගතය: `{global?: number, perProvider?: Record<string, number>}` |

**සත්යාපනය:** පරිපාලක විෂය පථය සහිත කළමනාකරණ සැසියක් අවශ්ය වේ.

---

## CLI මෙවලම් කළමනාකරණය

OmniRoute සමඟ ඒකාබද්ධ වන CLI මෙවලම් (antigravity, commandCode,
devin-cli ආදිය) කළමනාකරණය කරන්න. සම්පූර්ණ ලැයිස්තුව සඳහා [සපයන්නාගේ යොමුව](./PROVIDER_REFERENCE.md) බලන්න.

| ක්රමය | මාර්ගය                                  | විස්තරය                                                                                                                                                                                 |
| ----- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/cli-tools/all-statuses`           | සියලු CLI මෙවලම්වල තත්ත්වය (ස්ථාපනය කර තිබේද, අනුවාදය, අවසන් වරට දුටු වේලාව)                                                                                                            |
| GET   | `/api/cli-tools/status`                 | එක් CLI මෙවලමක් සඳහා තත්ත්ව විස්තර (`?tool=` විමසුම)                                                                                                                                    |
| POST  | `/api/cli-tools/apply`                  | මෙවලමක ජනනය කළ වින්යාසය ලියයි (`dryRun` මඟින් පෙරදසුනක් පෙන්වයි; බහාලුම්ගත කර ඇති විට `422` + `containerEphemeralTarget`; `migration` මඟින් පැරණි Codex YAML එකක් පිළිබඳ සටහනක් දක්වයි) |
| GET   | `/api/cli-tools/backups`                | CLI මෙවලම් වින්යාස උපස්ථ ලැයිස්තුගත කරයි                                                                                                                                                |
| POST  | `/api/cli-tools/backups`                | සියලු CLI මෙවලම් වින්යාසවල උපස්ථයක් සාදයි                                                                                                                                               |
| POST  | `/api/cli-tools/backups`                | ප්රතිසාධනය: ඉල්ලීම් අන්තර්ගතයේ `{tool, backupId}` සමඟ එකම අන්ත ලක්ෂ්යය භාවිත කිරීමෙන් එම උපස්ථය ප්රතිසාධනය කරයි                                                                         |
| GET   | `/api/cli-tools/antigravity-mitm`       | Antigravity MITM ප්රොක්සි තත්ත්වය ("antigravity-mitm" CLI මෙවලම)                                                                                                                        |
| POST  | `/api/cli-tools/antigravity-mitm/alias` | antigravity-mitm අන්වර්ථ නාම වින්යාස කරයි                                                                                                                                               |

**සත්යාපනය:** කළමනාකරණ සැසියක් අවශ්ය වේ.

---

## නියෝජිත කුසලතා

AI නියෝජිත කුසලතා කළමනාකරණය කරන්න (OpenAI හි අභිරුචි GPTවලට සමාන නමුත් නියෝජිතයින් සඳහාය).

| ක්රමය  | මාර්ගය                       | විස්තරය                                                                                                   |
| ------ | ---------------------------- | --------------------------------------------------------------------------------------------------------- |
| GET    | `/api/agent-skills`          | සියලුම නියෝජිත කුසලතා ලැයිස්තුගත කරන්න (අන්තර්ගත + අභිරුචි)                                               |
| GET    | `/api/agent-skills/[id]`     | නිශ්චිත නියෝජිත කුසලතාවක් ලබා ගන්න                                                                        |
| POST   | `/api/agent-skills`          | අභිරුචි නියෝජිත කුසලතාවක් සාදන්න — ඉල්ලීම් අන්තර්ගතය: `{name, description, prompt, model?, temperature?}` |
| PUT    | `/api/agent-skills/[id]`     | අභිරුචි නියෝජිත කුසලතාවක් යාවත්කාලීන කරන්න                                                                |
| DELETE | `/api/agent-skills/[id]`     | අභිරුචි නියෝජිත කුසලතාවක් මකන්න                                                                           |
| GET    | `/api/agent-skills/[id]/raw` | අමු ප්රේරකය + පාරදත්ත ලබා ගන්න (ක්රියාත්මක කිරීමකින් තොරව)                                                |
| POST   | `/api/agent-skills/generate` | ස්වාභාවික භාෂා විස්තරයකින් AI භාවිතයෙන් නව කුසලතාවක් ජනනය කරන්න                                           |

**සත්යාපනය:** කළමනාකරණ සැසියක් හෝ කළමනාකරණ විෂය පථය සහිත API යතුරක් අවශ්ය වේ.

---

## හැඹිලි කළමනාකරණය

අර්ථාන්විත හැඹිලිය සහ තර්කන හැඹිලිය කළමනාකරණය කරන්න.

| ක්රමය  | මාර්ගය                 | විස්තරය                                                                                                           |
| ------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| GET    | `/api/cache`           | හැඹිලි දළ විශ්ලේෂණය: මුළු ඇතුළත් කිරීම්, සාර්ථක ප්රතිසාධන අනුපාතය, තැටියේ ප්රමාණය                                 |
| GET    | `/api/cache/entries`   | හැඹිලිගත ඇතුළත් කිරීම් ලැයිස්තුගත කරන්න (පිටුකරණය සමඟ)                                                            |
| DELETE | `/api/cache/entries`   | හැඹිලි ඇතුළත් කිරීම් මකන්න (විමසුම් පරාමිති අනුව පෙරහන් කරන්න)                                                    |
| GET    | `/api/cache/stats`     | සවිස්තරාත්මක හැඹිලි සංඛ්යාලේඛන (සපයන්නා අනුව, මාදිලිය අනුව)                                                       |
| GET    | `/api/cache/reasoning` | තර්කන හැඹිලියේ තත්ත්වය (තර්කන නැවත ධාවනය සඳහා)                                                                    |
| DELETE | `/api/cache/reasoning` | තර්කන හැඹිලිය හිස් කරන්න — විමසුම් පරාමිති: `?toolCallId=<id>` (තනි) හෝ `?provider=<p>` හෝ පරාමිති නැතිව (සියල්ල) |

**සත්යාපනය:** කළමනාකරණ සැසියක් අවශ්ය වේ.

---

## මතක පද්ධතිය

ස්ථිර මතකය (FTS5 + දෛශික කාවැද්දීම්) කළමනාකරණය කරන්න.

| ක්රමය  | මාර්ගය             | විස්තරය                                                                              |
| ------ | ------------------ | ------------------------------------------------------------------------------------ |
| GET    | `/api/memory`      | මතක ඇතුළත් කිරීම් ලැයිස්තුගත කරන්න (විෂයපථය, වර්ගය, සෙවුම් විමසුම අනුව පෙරහන් කරන්න) |
| POST   | `/api/memory`      | නව මතක ඇතුළත් කිරීමක් සාදන්න — අන්තර්ගතය: `{scope, type, content, metadata?}`        |
| GET    | `/api/memory/[id]` | නිශ්චිත මතක ඇතුළත් කිරීමක් ලබා ගන්න                                                  |
| PUT    | `/api/memory/[id]` | මතක ඇතුළත් කිරීමක් යාවත්කාලීන කරන්න                                                  |
| DELETE | `/api/memory/[id]` | මතක ඇතුළත් කිරීමක් මකන්න                                                             |
| GET    | `/api/memory?q=`   | මතකය සොයන්න (FTS5 + දෛශික) — එම ප්රතිචාරය තුළම සංඛ්යාලේඛන ඇතුළත් වේ                  |

**සත්යාපනය:** කළමනාකරණ සැසියක් හෝ කළමනාකරණ විෂයපථයක් සහිත API යතුරක් අවශ්ය වේ.

---

## Webhooks

සිදුවීම් සඳහා webhook දායකත්ව කළමනාකරණය කරන්න.

| ක්රමය  | මාර්ගය                          | විස්තරය                                                                     |
| ------ | ------------------------------- | --------------------------------------------------------------------------- |
| GET    | `/api/webhooks`                 | සියලු webhook දායකත්ව ලැයිස්තුගත කරන්න                                      |
| POST   | `/api/webhooks`                 | webhook දායකත්වයක් සාදන්න — අන්තර්ගතය: `{url, events[], secret?, active?}`  |
| GET    | `/api/webhooks/[id]`            | නිශ්චිත webhook දායකත්වයක් ලබා ගන්න                                         |
| PUT    | `/api/webhooks/[id]`            | webhook දායකත්වයක් යාවත්කාලීන කරන්න                                         |
| DELETE | `/api/webhooks/[id]`            | webhook දායකත්වයක් මකන්න                                                    |
| GET    | `/api/webhooks/[id]/deliveries` | webhook එකක් සඳහා බෙදාහැරීම් ඉතිහාසය ලැයිස්තුගත කරන්න (සාර්ථක/අසාර්ථක ලොගය) |
| POST   | `/api/webhooks/[id]/test`       | webhook එකකට පරීක්ෂණ සිදුවීමක් යවන්න                                        |

**සත්යාපනය:** කළමනාකරණ සැසියක් අවශ්ය වේ.

සම්පූර්ණ සිදුවීම් වර්ග සඳහා [Webhooks රාමුව](../frameworks/WEBHOOKS.md) බලන්න.

---

## කුසලතා රාමුව

කුසලතා (නියෝජිත දිගු රාමුව) කළමනාකරණය කරන්න.

| ක්රමය  | මාර්ගය                   | විස්තරය                                                                                             |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------- |
| GET    | `/api/skills`            | ස්ථාපිත සියලු කුසලතා ලැයිස්තුගත කරන්න (ගොඩනඟා ඇති + අභිරුචි)                                        |
| POST   | `/api/skills/install`    | දේශීය මාර්ගයකින් හෝ URL එකකින් කුසලතාවක් ස්ථාපනය කරන්න                                              |
| DELETE | `/api/skills/[id]`       | කුසලතාවක් අස්ථාපනය කරන්න                                                                            |
| PUT    | `/api/skills/[id]`       | කුසලතාවක් සක්රිය හෝ අක්රිය කරන්න — අන්තර්ගතය: `{enabled?: boolean, mode?: "on" \| "off" \| "auto"}` |
| POST   | `/api/skills/executions` | කුසලතාවක් ක්රියාත්මක කරන්න — අන්තර්ගතය: `{skillName, apiKeyId, input?, sessionId?}`                 |
| GET    | `/api/skills/executions` | සියලු කුසලතාවල ක්රියාත්මක කිරීමේ ඉතිහාසය ලැයිස්තුගත කරන්න (`?apiKeyId=` අනුව පෙරහන් කරන්න)          |

**සත්යාපනය:** කළමනාකරණ සැසියක් හෝ කළමනාකරණ විෂයපථ API යතුරක් අවශ්ය වේ.

සම්පූර්ණ විස්තර සඳහා [කුසලතා රාමුව](../frameworks/SKILLS.md) බලන්න.

---

## ප්ලගින

OmniRoute ප්ලගින (තෙවන පාර්ශ්ව දිගු) කළමනාකරණය කරන්න.

| ක්රමය  | මාර්ගය                             | විස්තරය                            |
| ------ | ---------------------------------- | ---------------------------------- |
| GET    | `/api/plugins`                     | ස්ථාපිත ප්ලගින ලැයිස්තුගත කරන්න    |
| POST   | `/api/plugins/marketplace/install` | වෙළඳපොළෙන් ප්ලගිනයක් ස්ථාපනය කරන්න |
| DELETE | `/api/plugins/[name]`              | ප්ලගිනයක් අස්ථාපනය කරන්න           |
| POST   | `/api/plugins/[name]/activate`     | ප්ලගිනයක් සක්රිය කරන්න             |
| POST   | `/api/plugins/[name]/deactivate`   | ප්ලගිනයක් අක්රිය කරන්න             |
| GET    | `/api/plugins/[name]/config`       | ප්ලගින වින්යාසය ලබාගන්න            |
| PUT    | `/api/plugins/[name]/config`       | ප්ලගින වින්යාසය යාවත්කාලීන කරන්න   |

**සත්යාපනය:** කළමනාකරණ සැසියක් අවශ්ය වේ.

සම්පූර්ණ විස්තර සඳහා [ප්ලගින රාමුව](../frameworks/PLUGIN_SDK.md) බලන්න.

---

## ඡායා මාර්ගගත කිරීම

සැපයුම්කරුවන්ගේ ඡායා / A-B සැසඳීම **ස්වාධීන REST අතුරුමුහුණතක් නොවේ** — එය සංයුක්ත මාර්ගගත කිරීම හරහා වින්යාස කෙරේ ([ස්වයංක්රීය-සංයෝජනය](../routing/AUTO-COMBO.md) බලන්න). එක් එක් සංයෝජනය සඳහා වන සැසඳීමේ ප්රමිතික `GET /api/combos/metrics` මඟින් සපයනු ලැබේ.

---

## ආරක්ෂක සීමා

ධාවන කාල ආරක්ෂක සීමා (PII හඳුනාගැනීම, ප්රේරක එන්නත් හඳුනාගැනීම, දෘශ්ය සම්බන්ධකරණය) පරීක්ෂා කරන්න. සෑම ඉල්ලීමකදීම ආරක්ෂක සීමා ක්රියාත්මක වේ; එක් එක් ඇමතුම සඳහා ඉවත් වීම `x-omniroute-disabled-guardrails` ඉල්ලීම් ශීර්ෂය හරහා සිදු වේ — ස්ථිරව පවතින සක්රිය/අක්රිය අතුරුමුහුණතක් නොමැත.

| ක්රමය | මාර්ගය                 | විස්තරය                                                                                                          |
| ----- | ---------------------- | ---------------------------------------------------------------------------------------------------------------- |
| GET   | `/api/guardrails`      | ලියාපදිංචි ආරක්ෂක සීමා සහ ඒවායේ තත්ත්වය ලැයිස්තුගත කරන්න (නම / සක්රියද / ප්රමුඛතාව)                              |
| POST  | `/api/guardrails/test` | නියැදි ආදානයක් මත ඇමතුමට පෙර නලමාර්ගය අත්හදා බැලීමක් ලෙස ධාවනය කරන්න — අන්තර්ගතය: `{input, disabledGuardrails?}` |

**සත්යාපනය:** කළමනාකරණ සැසියක් අවශ්ය වේ.

සම්පූර්ණ විස්තර සඳහා [ආරක්ෂාව > ආරක්ෂක සීමා](../security/GUARDRAILS.md) බලන්න.

---

---

## සත්යාපනය

අක්තපත්ර කාණ්ඩ හතර (dashboard session, local CLI token, `oma_live_…` Access Token, manage-scoped API key) සහ ඒවා inference keys වලින් වෙනස් වන ආකාරය සඳහා [කළමනාකරණ සත්යාපනය](../guides/MANAGEMENT-AUTH.md) බලන්න.

- Dashboard routes (`/dashboard/*`) `auth_token` cookie භාවිත කරයි
- Login සඳහා සුරැකි password hash භාවිත කරයි; fallback ලෙස `INITIAL_PASSWORD` භාවිත කරයි
- `requireLogin` `/api/settings/require-login` හරහා toggle කළ හැක
- `REQUIRE_API_KEY=true` වන විට `/v1/*` routes සඳහා විකල්පයක් ලෙස Bearer API key අවශ්ය වේ
- මෙම යොමුවේ "management token" / "management-scoped API key" යන්නෙන් අදහස් වන්නේ එම මාර්ගෝපදේශයේ සඳහන් කාණ්ඩවලින් එකකි — නිර්වචනය නොකළ අමතර secret type එකක් නොවේ

> **අනුකූලතාව බිඳෙන වෙනසක් (v3.8.0)** — `/api/v1/agents/tasks/*` සහ cooldown management endpoints සඳහා දැන් **management auth** (dashboard `auth_token` cookie එකක් හෝ management-scoped API key එකක්) අවශ්ය වේ. මීට පෙර සත්යාපනයකින් තොරව මෙම routes ඇමතූ clients වෙත `401 Unauthorized` ලැබෙනු ඇත. `588a0333` commit එක (`fix(auth): require management auth for agent and cooldown APIs`) බලන්න.