pjandro/OmniRoute
1
0
Fork 0
mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-09-18 12:52:25 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
af2002a49349ca60d7e804c7d0470ac4e58fee97
OmniRoute/docs/i18n/am/docs/reference/API_REFERENCE.md
Diego Rodrigues de Sa e Souza 58f88a83e4 feat(i18n): 7 new locales — Hausa, Yoruba, Igbo, Amharic, Uzbek, Georgian, Armenian (66 locales) (#13727) 
Batch 3 (last) of the locale-expansion plan: ha, yo, ig, am, uz, ka, hy on every surface — dashboard catalog, docs mirror (22-file core + llm.txt + CHANGELOG), CLI catalog, README flag block, locale tables and 🌐 language bars. Also closes the key gap the batch-1 (43 keys) and batch-2 (10 keys) catalogs carried since their base merges, fixes the Igbo "Model" copy and allowlists the Uzbek cognate. Translation-ratio baseline covers 65 locales.

⚠️ base-red inherited: #12732
2026-09-15 09:50:01 -03:00

1775 lines
141 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# API_REFERENCE (አማርኛ)
🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇨🇿 [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) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
---
---
title: "የAPI ማጣቀሻ"
version: 3.8.51
lastUpdated: 2026-08-31
---
# የAPI ማጣቀሻ
🌐 **Languages:** 🇺🇸 [English](../../../../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) · 🇨🇿 [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) · 🇱🇰 [si](../../../si/docs/reference/API_REFERENCE.md) · 🇸🇰 [sk](../../../sk/docs/reference/API_REFERENCE.md) · 🇸🇮 [sl](../../../sl/docs/reference/API_REFERENCE.md) · 🇷🇸 [sr](../../../sr/docs/reference/API_REFERENCE.md) · 🇸🇪 [sv](../../../sv/docs/reference/API_REFERENCE.md) · 🇰🇪 [sw](../../../sw/docs/reference/API_REFERENCE.md) · 🇮🇳 [ta](../../../ta/docs/reference/API_REFERENCE.md) · 🇮🇳 [te](../../../te/docs/reference/API_REFERENCE.md) · 🇹🇭 [th](../../../th/docs/reference/API_REFERENCE.md) · 🇹🇷 [tr](../../../tr/docs/reference/API_REFERENCE.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/API_REFERENCE.md) · 🇵🇰 [ur](../../../ur/docs/reference/API_REFERENCE.md) · 🇺🇿 [uz](../../../uz/docs/reference/API_REFERENCE.md) · 🇻🇳 [vi](../../../vi/docs/reference/API_REFERENCE.md) · 🇳🇬 [yo](../../../yo/docs/reference/API_REFERENCE.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/API_REFERENCE.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/API_REFERENCE.md)
የOmniRoute API ዋና ማጣቀሻ። የይፋውን `/v1` ገጽታ እና በብዛት ጥቅም ላይ የሚውሉትን የአስተዳደር መዳረሻዎች ይሸፍናል፤ በማሽን የሚነበበው [`docs/openapi.yaml`](../openapi.yaml) እና በ`src/app/api/` ሥር ያለው የመስመር ዛፍ የተሟሉ ምንጮች ናቸው።
---
## የይዘት ማውጫ
- [የውይይት ማጠናቀቂያዎች](#chat-completions)
- [ብቸኛ የሚተዳደሩ የክፍለ ጊዜ ኪራዮች](#exclusive-managed-session-leases)
- [መክተቻዎች](#embeddings)
- [ምስል ማመንጨት](#image-generation)
- [የሰነድ OCR](#document-ocr)
- [ሞዴሎችን መዘርዘር](#list-models)
- [የአቅራቢ ፕለጊን ማኒፌስት](#provider-plugin-manifest)
- [የተኳኋኝነት መገልገያ ነጥቦች](#compatibility-endpoints)
- [የፋይሎች API](#files-api)
- [የባች API](#batches-api)
- [የፍለጋ API](#search-api)
- [የWebSocket ዥረት](#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` ያዘጋጁ (ከno-cache ጋር ተመሳሳይ ነው፤ በእያንዳንዱ ጥሪ የሚኖረውን ተጨማሪ የቶከን/ወጪ ጫና ያስወግዳል) |
| `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`። እነዚህ በውይይት ማጠናቀቂያዎች፣ `/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)።
> **የመሸጎጫ መገኘት ወጪ ትርጉም፦** በሴማንቲክ መሸጎጫ HIT (`X-OmniRoute-Cache-Hit: true`) ላይ ወደ ላይኛው አቅራቢ ምንም ጥሪ አይደረግም፤ ስለዚህ `X-OmniRoute-Response-Cost` `0.0000000000` ይሆናል (መገኘቱን ለማቅረብ የሚያስፈልገው **ተጨማሪ** ወጪ)። የመጀመሪያው/ሊኖር የነበረው ወጪ በ`X-OmniRoute-Cost-Saved` ውስጥ ለብቻው ሪፖርት ይደረጋል። የክፍያ አጠቃቀም ስርዓቶች `X-OmniRoute-Response-Cost`ን መደመር አለባቸው (የመሸጎጫ መገኘቶች ምንም ወጪ የላቸውም)፤ የመሸጎጫ ትንታኔዎች `X-OmniRoute-Cost-Saved`ን ማጠቃለል ይችላሉ።
## ብቸኛ የሚተዳደሩ የክፍለ ጊዜ ሊዞች
ብቸኛ የሚተዳደር የክፍለ ጊዜ ሊዝ በምርጫ የሚነቃ፣ ከደንበኛ ዓይነት ነጻ የሆነ የማስተላለፊያ ውል ነው፦ አንድ ንቁ ባለቤት
አንድ ብቁ የOmniRoute ግንኙነት ይይዛል። ሞዴል አያከራይም፣ OAuthን አይጠይቅም፣ አንድን
የተወሰነ ደንበኛ አይለይም፣ ወይም አንድን የተወሰነ አቅራቢ አይጠይቅም።
ማረጋገጫ የሚያደርገው API ቁልፍ `lease:exclusive` ወሰን እና በግልጽ የተቀመጠ ባዶ ያልሆነ
የ`allowedConnections` ዝርዝር ሊኖረው ይገባል። የውሂብ ጎታው የለውጥ ድንበር ቁልፍ
ሲፈጠርና ከፊል ዝማኔዎች ሲደረጉ ሁለቱንም መስኮች በጋራ ያስገድዳል።
```http
POST /api/v1/session-leases
Authorization: Bearer <managed-api-key>
Content-Type: application/json
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
{"action":"acquire","model":"glm/glm-4.6"}
```
የተሳኩ የማግኘት፣ የማደስ እና የመልቀቅ ምላሾች የጊዜ ማህተሞችን፣ `state`ን እና ትክክለኛውን አዎንታዊ
`generation` ያሳያሉ፣ ነገር ግን የተመረጠውን ግንኙነት ወይም የማረጋገጫ መረጃዎችን ፈጽሞ አያሳዩም። ማደስና መልቀቅ
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 ቁልፍ እና ትክክለኛው
ንቁ generation በአንድ የውሂብ ጎታ ግብይት ውስጥ የታጠረ ነው። `displayName` የተከረከመው የተዋቀረ
የግንኙነት ስም ብቻ ነው፤ ደህንነቱ የተጠበቀ የተዋቀረ ስም ከሌለ `null` ይሆናል። OmniRoute
ኢሜይልን ወይም የመነጨ የመለያ ማንነትን በምትኩ ፈጽሞ አይጠቀምም። የአቅራቢው እሴት ስሱ ያልሆነ የማሳያ መለያ ሲሆን ፈጽሞ
የመነጨ ተኳሃኝ-አቅራቢ መለያ አይደለም። የማረጋገጫ መረጃዎች፣ ቶከኖች፣ ኩኪዎች፣ ያልተሰናዱ የግንኙነት ወይም API
ቁልፍ መለያዎች፣ የባለቤት ሃሾች፣ የማጠሪያ ሚስጥሮች እና ውስጣዊ የማስተላለፊያ ውሂብ አይካተቱም።
በተሳሳተ-ቁልፍ፣ በተሳሳተ-ባለቤት፣ ጊዜው ባለፈበት-generation፣ በጠፋ፣ ጊዜው ባለፈበት፣ በተለቀቀ እና ዋጋ ባጣ ፍለጋ ሁሉ
ያለ ግንኙነት ሜታዳታ ተመሳሳዩን `409 LEASE_FENCE_STALE` ስህተት ይመልሳሉ። የአቅም-መጠበቂያ ምላሽን የተቀበለ ደንበኛ ሊመረምረው የሚችል ንቁ ትስስር የለውም። ማስተላለፉ ንቁ ሊዝን
ሲያሸጋግር፣ ተመሳሳዩ generation ትክክለኛ ሆኖ ይቆያል እና ሁኔታው አዲሱን ትስስር በአቶሚክ መንገድ ይመልሳል፣ አሮጌውን ግን ፈጽሞ አይመልስም።
ማግኘት፣ ማደስ፣ መልቀቅ እና የመጠበቂያ ምላሾች የቀድሞ ቅርጾቻቸውን ስለሚይዙ ነባር ደንበኞች
ሳይለወጡ ይቆያሉ።
ይህ የአገልጋይ ውል መደበኛውን OpenAI Codex `/status` አይቀይርም። መደበኛው Codex በአሁኑ ጊዜ የእሱን
የሞዴል አቅራቢ እና አብሮ የተገነባውን የማረጋገጫ/መለያ ሁኔታ ሪፖርት ያደርጋል፣ ነገር ግን የዘፈቀደ ብጁ
የአቅራቢ መለያ ሜታዳታን አያሳይም፤ የወደፊት የደንበኛ ውህደት ይህን እርምጃ መጥራት እና
`connection.displayName`ን እንዴት እንደሚያሳይ መወሰን አለበት።
ከዚያ እያንዳንዱ የሚተዳደር የማመላከቻ ጥያቄ ሁለቱንም የቁጥጥር ራስጌዎች ይልካል፦
```http
X-OmniRoute-Lease-Owner: vlo_<43-base64url-characters>
X-OmniRoute-Lease-Generation: 1
```
ትክክለኛው ባለቤት፣ generation፣ ንቁ ግንኙነት እና ማረጋገጫ ያደረገው API ቁልፍ ከእያንዳንዱ
የሚደገፍ upstream ሙከራ ወዲያውኑ በፊት ይታጠራሉ። ባለቤቱን እና generationን በሌላ ቁልፍ እንደገና ማጫወት፣
ያ ቁልፍ ተመሳሳዩን ግንኙነት ቢፈቅድም እንኳ ይከሽፋል። ያልተሰናዱ ባለቤቶች አይከማቹም፣ በምዝግብ አይመዘገቡም፣ በ
ጥያቄው ቅጽበታዊ ቅጂ ውስጥ አይቆዩም ወይም upstream አይተላለፉም።
ጊዜያዊ ፉክክር 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`
የመጭመቂያ ዕቅዱን በእያንዳንዱ ጥያቄ ላይ የሚሽር ቅንብር። ከፍተኛው ቅድሚያ — የማስተላለፊያ-combo
መሻርን፣ ንቁውን መገለጫ፣ ራስ-አነሳሽን እና የፓነሉን Default ያሸንፋል። እሴቶች፦
| እሴት | ውጤት |
| ------------- | -------------------------------------------------- |
| `off` | ለዚህ ጥያቄ ምንም መጭመቅ አይኖርም። |
| `default` | ከፓነሉ የተገኘው Default መገለጫ (ንቁውን መገለጫ ችላ ይላል)። |
| `engine:<id>` | ሲነቃ አንድ ነጠላ engine፣ ለምሳሌ `engine:rtk`። |
| `<combo>` | በስም የሚዛመድ የተሰየመ combo (ለፊደል አቀማመጥ ግድየለሽ)፣ ከዚያ በid። |
ማስታወሻዎች፦
- ያልታወቁ እሴቶች ችላ ይባላሉ (ጥያቄው ፈጽሞ ውድቅ አይደረግም)፤ መፍታቱ ወደ መደበኛው የኦፕሬተር ቅድሚያ ይቀጥላል።
- ብዙ combos ተመሳሳይ ስም ካላቸው፣ ቆራጥ የሆነ ማዛመድ ለማግኘት የcomboውን **id** ያስተላልፉ።
- ስሙ `off` ወይም `default` የሆነ combo በስም ሊመረጥ አይችልም (እነዚያ ቁልፍ ቃላት በመጀመሪያ ይተረጎማሉ)፤ እንዲህ ያለውን combo በidው ያመልክቱ።
- ዋናው የመጭመቂያ መቀየሪያ ጥብቅ መግቢያ ነው፦ መጭመቅ በዓለም አቀፍ ደረጃ ሲሰናከል፣ ይህ ራስጌ ሊያነቃው አይችልም።
ተግባራዊ የተደረገው ዕቅድ በምላሽ ራስጌው ውስጥ ተመልሶ ይታያል፦
```
X-OmniRoute-Compression: <mode>; source=<source>
```
እዚህ `<source>` ከ`request-header`፣ `routing-override`፣ `active-profile`፣ `auto-trigger`፣ `default` ወይም `off` አንዱ ነው።
---
## ኤምቤዲንጎች
```bash
POST /v1/embeddings
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "nebius/Qwen/Qwen3-Embedding-8B",
"input": "The food was delicious"
}
```
የሚገኙ አቅራቢዎች፦ Nebius, OpenAI, Mistral, Together AI, Fireworks, NVIDIA, **OpenRouter**, Jina AI።
የካታሎግ መለያዎች `provider/model` ቅርጸት አላቸው (ለምሳሌ፦ `jina-ai/jina-embeddings-v5-omni-small`)። በሬጂስትሪው ውስጥ የሚታዩ አቅራቢ ያልተጠቀሰባቸው የJina ሞዴል መለያዎችም (ለምሳሌ `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`)፤ ኤምቤዲንጎችን ወይም 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` ጥያቄ ይሆናል።
- ግልጽ የሞዳሊቲ ሜታዳታ የሌላቸው ያልታወቁ/ተለዋዋጭ ሞዴሎች የተዋቀረ ግቤትን በHTTP 400 ውድቅ ያደርጋሉ።
```json
{
"model": "jina-ai/jina-embeddings-v5-omni-small",
"input": [
{ "type": "text", "text": "A red bicycle" },
{
"type": "image",
"source": { "type": "url", "url": "https://example.com/bicycle.png" }
}
],
"dimensions": 512,
"encoding_format": "float"
}
```
የማይደገፉ የሞዴል/ሞዳሊቲ ጥምረቶች ንጥሉን በግድ ከመቀየር ይልቅ HTTP 400 ይመልሳሉ። በቀድሞ የሕብረቁምፊ/ቶከን ጥያቄዎች ላይ ያሉ ግቤት-ያልሆኑ
የቅጥያ መስኮች ሳይቀየሩ መተላለፋቸውን ይቀጥላሉ።
```bash
# ሁሉንም የኤምቤዲንግ ሞዴሎች ዘርዝር
GET /v1/embeddings
```
---
## ምስል ማመንጨት
```bash
POST /v1/images/generations
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "openai/gpt-image-2",
"prompt": "በተራሮች ላይ የሚታይ ውብ የፀሐይ መጥለቂያ",
"size": "1024x1024"
}
```
የሚገኙ አቅራቢዎች፦ OpenAI (GPT Image 2)፣ xAI (Grok Image)፣ Together AI (FLUX)፣ Fireworks AI፣ Nebius (FLUX)፣ Hyperbolic፣ NanoBanana፣ **OpenRouter**፣ SD WebUI (አካባቢያዊ)፣ ComfyUI (አካባቢያዊ)።
```bash
# ሁሉንም የምስል ሞዴሎች ዘርዝር
GET /v1/images/generations
```
---
## የሰነድ OCR
```bash
POST /v1/ocr
Authorization: Bearer your-api-key
Content-Type: application/json
{
"model": "mistral/mistral-ocr-latest",
"document": {
"type": "document_url",
"document_url": "https://example.com/invoice.pdf"
}
}
```
`model` በ`provider/model` ቅድመ-ቅጥያ የOCR አቅራቢውን ይመርጣል፤ ቅድመ-ቅጥያ የሌለው የሞዴል መለያ (ለምሳሌ
`mistral-ocr-latest`) ወደ ተመዘገበለት አቅራቢ ይመራል፣ እንዲሁም `model` ካልተጠቀሰ ነባሪው
Mistral (`mistral-ocr-latest`) ነው። የተመዘገቡ አቅራቢዎች (`open-sse/config/ocrRegistry.ts`)፦
| የአቅራቢ መለያ | የሞዴል መለያ | የ`model` እሴት | ማስታወሻዎች |
| ----------------------------- | -------------------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `mistral` | `mistral-ocr-latest` | `mistral/mistral-ocr-latest` (ወይም ቅድመ-ቅጥያ የሌለው `mistral-ocr-latest`) | የተመሳሰለ — ምላሹ ከአንድ upstream ጥሪ በቀጥታ ይመለሳል። |
| `azure-document-intelligence` | `prebuilt-read` | `azure-document-intelligence/prebuilt-read` | ያልተመሳሰለ upstream (`analyze` + ሁኔታ መጠየቅ) — ከታች ይመልከቱ። |
| `vertex-deepseek-ocr` | `deepseek-ocr-maas` | `vertex-deepseek-ocr/deepseek-ocr-maas` | የተመሳሰለ፣ በVertex AI `openapi/chat/completions` አጋር endpoint በኩል — ለማረጋገጫ/URL ከታች ይመልከቱ። |
ሦስቱም አቅራቢዎች ተመሳሳይ የMistral ቅርጽ ባለው body ምላሽ ይሰጣሉ፦
```json
{
"pages": [{ "index": 0, "markdown": "# የወጣ ጽሑፍ..." }],
"model": "mistral-ocr-latest",
"usage_info": { "pages_processed": 1 }
}
```
### የAzure Document Intelligence የሁኔታ መጠየቂያ ፍሰት
የAzure Document Intelligence `analyze` API ያልተመሳሰለ ነው፦ የመጀመሪያው ጥያቄ body ከመመለስ ይልቅ
የ`Operation-Location` header ይመልሳል፣ ውጤቱም ሁኔታውን በተደጋጋሚ በመጠየቅ መገኘት አለበት። handler
(`open-sse/handlers/ocr.ts`) ያንን URL በየሰከንዱ እስከ 30 ሙከራዎች ድረስ ይጠይቃል፤ `ok` ያልሆነ የሁኔታ መጠየቂያ ምላሽ ወይም `"failed"` ሁኔታ ሲያጋጥም ወዲያውኑ ይከሽፋል (ሁኔታውን መጠየቁን
አይቀጥልም)፣ እንዲሁም የሙከራ ገደቡ ካለቀ በኋላ ክዋኔው አሁንም እየሰራ ከሆነ `504` ይመልሳል። የመጨረሻው የAzure ምላሽ
ወደ ጠሪው ከመመለሱ በፊት Mistral የሚጠቀምበትን ተመሳሳይ የ`pages`/`markdown` ቅርጽ እንዲኖረው ይደረጋል፣
ስለዚህ የደንበኛ ኮድ ለአቅራቢው የተለየ አያያዝ ማድረግ አያስፈልገውም።
### የVertex AI DeepSeek OCR ማረጋገጫ እና የendpoint መፍታት
`vertex-deepseek-ocr` OmniRoute ለውይይት/ምስል ትራፊክ አስቀድሞ የሚደግፈውን ተመሳሳይ የVertex AI ማረጋገጫ
(`open-sse/executors/vertex.ts`) እንደገና ይጠቀማል፦ የግንኙነቱ API key ወይም የService Account JSON ማረጋገጫ መረጃ
(በJWT-bearer ፍሰት አማካኝነት ለአጭር ጊዜ የሚሰራ OAuth access token እንዲሆን የሚቀየር) ወይም አስቀድሞ የተፈጠረና እንዳለ ጥቅም ላይ የሚውል 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
→ ሁሉንም የውይይት፣ embedding እና የምስል ሞዴሎችን + ጥምረቶችን በOpenAI ቅርጸት ይመልሳል
```
### የሞዴል id ቅድመ ቅጥያዎች (`?prefix=`)
አብዛኞቹ ሞዴሎች በ**አቅራቢ ቅድመ ቅጥያ** ስር ይታወቃሉ። የሚያገኙት ቅድመ ቅጥያ በ
`MODELS_CATALOG_PREFIX_MODE` የባህሪ ጠቋሚ የሚቆጣጠር ሲሆን፣ በጥያቄ መለኪያ **ለእያንዳንዱ ጥያቄ** ሊተካ ይችላል — ይህም የአገልጋዩን አጠቃላይ
ቅንብር ለሌሎች ሁሉ ሳይቀይር ንጹሕ ዝርዝር ለሚፈልግ ደንበኛ ጠቃሚ ነው፦
```bash
GET /v1/models?prefix=alias # ለእያንዳንዱ ሞዴል አንድ id — አጭሩ የቅጽል ስም ቅድመ ቅጥያ
GET /v1/models?prefix=dual # ሁለቱም ቅርጾች (የአገልጋዩ ነባሪ)
GET /v1/models?prefix=canonical # ሙሉው የአቅራቢ-id ቅድመ ቅጥያ ብቻ
```
| ሁነታ | የሚያወጣው | ማስታወሻዎች |
| ----------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `dual` | `cc/claude-sonnet-4-6` **እና** `claude/claude-sonnet-4-6` | **ነባሪ።** ሁለቱም ids ወደ ተመሳሳይ ሞዴል ይመራሉ፤ ከሁለቱ ቅርጾች አንዱን በቋሚነት ያስቀመጡ የደንበኛ ቅንብሮች መስራታቸውን እንዲቀጥሉ ተይዟል። የካታሎጉን መጠን በግምት እጥፍ ያደርገዋል። |
| `alias` | `cc/claude-sonnet-4-6` | ለእያንዳንዱ ሞዴል አንድ ግቤት። የተለየ ቅጽል ስም የሌላቸው አቅራቢዎችም አሁንም ግቤታቸውን ያወጣሉ፣ ስለዚህ ምንም ነገር አይጠፋም። |
| `canonical` | `claude/claude-sonnet-4-6` | በሙሉው የአቅራቢ-id ቅድመ ቅጥያ ስር ለእያንዳንዱ ሞዴል አንድ ግቤት። የተለየ ቅጽል ስም የሌላቸው አቅራቢዎች (ለምሳሌ `antigravity/…`፣ `agy/…`) እዚህም ነጠላ idቸውን ያወጣሉ፣ ስለዚህ ምንም ነገር አይጠፋም። |
የ`dual` ሁነታ አንጸባራቂ ያለ ጥያቄ መለኪያውም ሊታወቅ ይችላል፦ ወደ ዋናው id
የሚያመለክት `parent` መስክ ይይዛል።
የሞዴል መራጭ የሚያሳዩ ደንበኞች `?prefix=alias` መጠየቅ አለባቸው —
[OmniCopilot VS Code extension](../guides/VSCODE-COPILOT.md) የሚያደርገውም ይህንን ነው።
### ያለ-አስተሳሰብ የሞዴል ልዩነቶች
አስተሳሰብን ለሚደግፉ የClaude ሞዴሎች፣ `/v1/models` idው `claude-3-omniroute-no-thinking/` የሚለው ቅድመ ቅጥያ ያለውን **ያለ-አስተሳሰብ** ልዩነትም ያሳውቃል፦
```
claude-3-omniroute-no-thinking/<provider>/<model>
```
ይህን id መምረጥ (ለምሳሌ፣ ሁልጊዜ `thinking` ብሎክ በሚያያይዝ የClaude Code ቅንብር ውስጥ) ምክንያታዊ አስተሳሰብን በማገድ ወደ እውነተኛው `<provider>/<model>` መልሶ ይፈታዋል — በ`/v1/messages` መንገድ ላይ `thinking:{type:"disabled"}`፣ ወይም በ`/v1/chat/completions` መንገድ ላይ የ`reasoning`/`reasoning_effort` መስኮች ይወገዳሉ። ልዩነቱ የሚዘረዘረው አስተሳሰብን ለሚደግፉ **እና** `disabled`ን ለሚያከብሩ የClaude-ቤተሰብ ሞዴሎች ብቻ ነው (ስለዚህ፣ ለምሳሌ `disabled`ን የማይቀበሉ adaptive-only ሞዴሎች አይካተቱም)። ኦፕሬተሮች `ModelSpec.noThinkingAlias`ን በመጠቀም ልዩነቱን ለእያንዳንዱ ሞዴል በግድ ማብራት ወይም ማጥፋት ይችላሉ።
---
## የአቅራቢ ተሰኪ ማኒፌስት
```bash
GET /api/v1/provider-plugin-manifest
```
በBifrost፣ CLIProxyAPI እና ወደፊት በሚኖሩ sidecar ራውተሮች ጥቅም ላይ የሚውለውን ለJSON ደህንነቱ የተጠበቀ የአቅራቢ ተሰኪ ማኒፌስት ይመልሳል። ምላሹ ከTypeScript የአቅራቢ መዝገብ የሚፈጠር ሲሆን፣ ሆን ተብሎ OAuth የደንበኛ ምስጢሮችን፣ የአሂድ ጊዜ አካባቢ መፍታትን፣ አስፈጻሚ ተግባራትን፣ የጥያቄ ራስጌዎችን እና የመለያ ውሂብን አያካትትም።
አንድ sidecar ከሂደት ውጭ ሲሰራ እና
`open-sse/config/providerPluginManifestRegistry.ts`ን በቀጥታ ማስመጣት ሳይችል ሲቀር ይህን የመዳረሻ ነጥብ ይጠቀሙ።
---
## የተኳኋኝነት መዳረሻ ነጥቦች
| ዘዴ | ዱካ | ቅርጸት |
| ---- | ----------------------------------------- | ------------------------------------ |
| POST | `/v1/chat/completions` | OpenAI |
| POST | `/v1/messages` | Anthropic |
| POST | `/v1/responses` | OpenAI Responses |
| POST | `/v1/embeddings` | OpenAI |
| POST | `/v1/images/generations` | OpenAI Images |
| POST | `/v1/images/edits` | OpenAI Images (ማርትዕ/መሙላት) |
| POST | `/v1/videos/generations` | የOpenAI ቅጥ ያለው የቪዲዮ ማመንጨት |
| POST | `/v1/music/generations` | የOpenAI ቅጥ ያለው የሙዚቃ ማመንጨት |
| POST | `/v1/audio/transcriptions` | OpenAI Audio (STT) |
| POST | `/v1/audio/speech` | OpenAI TTS (የድምፅ ይዘት ይመልሳል) |
| POST | `/v1/rerank` | የCohere/Voyage ቅጥ ያለው ዳግም ደረጃ አሰጣጥ |
| POST | `/v1/classify` | Jina ምደባ (`api.jina.ai`) |
| POST | `/v1/segment` | Jina ከፋይ (`segment.jina.ai`) |
| POST | `/v1/moderations` | OpenAI Moderations |
| GET | `/v1/models` | OpenAI |
| POST | `/v1/messages/count_tokens` | Anthropic |
| GET | `/v1beta/models` | Gemini |
| POST | `/v1beta/models/{...path}` | Gemini generateContent |
| POST | `/v1/api/chat` | Ollama |
| GET | `/api/v1/vscode/{token}/` | የOpenAI ካታሎግ ተለዋጭ ስም |
| GET | `/api/v1/vscode/{token}/models` | የOpenAI ሞዴሎች ተለዋጭ ስም |
| POST | `/api/v1/vscode/{token}/chat/completions` | በቶከን የተደረገ የOpenAI ተለዋጭ ስም |
| POST | `/api/v1/vscode/{token}/responses` | በቶከን የተደረገ የOpenAI Responses ተለዋጭ ስም |
| POST | `/api/v1/vscode/{token}/api/chat` | በቶከን የተደረገ የOllama ተለዋጭ ስም |
| GET | `/api/v1/vscode/{token}/api/tags` | በቶከን የተደረገ የOllama መለያዎች ተለዋጭ ስም |
ሁሉም POST መስመሮች ተመሳሳይ ቅርጽን ይከተላሉ፦ `Bearer your-api-key` + በZod የተረጋገጠ JSON ይዘት (`v1RerankSchema`፣ `v1ModerationSchema`፣ `v1AudioSpeechSchema`፣ ወዘተ፤ `src/shared/validation/schemas.ts`ን ይመልከቱ)። የስኪማ ማረጋገጥ ሲከሽፍ 4xx ይመለሳል።
`Authorization: Bearer ...`ን ማያያዝ ለማይችሉ ደንበኞች፣ OmniRoute በURL ውስጥ የAPI ቁልፎችን በመጠይቅ-ሕብረቁምፊ ተኳኋኝነት (`?token=...`፣ `?apiKey=...`፣ `?api_key=...`፣ `?key=...`) ወይም ከታች በተመዘገቡት የተለዩ `/api/v1/vscode/{token}/...` መዳረሻ ነጥቦች በኩል ይቀበላል።
```bash
# ዳግም ደረጃ አሰጣጥ
POST /v1/rerank { "model": "jina-ai/jina-reranker-v3.5", "query": "...", "documents": ["..."] }
# Jina ምደባ (የFoundation API ማረጋገጫዎች)
POST /v1/classify { "model": "jina-embeddings-v5-text-small", "input": ["..."], "labels": ["a", "b"] }
# Jina ከፋይ
POST /v1/segment { "content": "...", "return_chunks": true }
# Jina ፍለጋ (s.jina.ai፤ የአቅራቢ ተለዋጭ ስሞች፦ jina-search, jina-ai, jina)
POST /v1/search { "query": "...", "provider": "jina-search" }
# የይዘት ቁጥጥር
POST /v1/moderations { "model": "omni-moderation-latest", "input": "..." }
# TTS — የaudio/mpeg ይዘትን (ወይም የተጠየቀውን ቅርጸት) ይመልሳል
POST /v1/audio/speech { "model": "openai/tts-1", "input": "Hello", "voice": "alloy" }
# የምስል ማርትዕ (multipart)
POST /v1/images/edits -F image=@input.png -F prompt="..." -F mask=@mask.png
# የቪዲዮ / ሙዚቃ ማመንጨት (በአቅራቢ ቅድመ ቅጥያ የተጀመረ የሞዴል መታወቂያ)
POST /v1/videos/generations { "model": "runway/gen-3", "prompt": "..." }
POST /v1/music/generations { "model": "suno/v3.5", "prompt": "..." }
```
### የተለዩ የአቅራቢ መስመሮች
```bash
POST /v1/providers/{provider}/chat/completions
POST /v1/providers/{provider}/embeddings
POST /v1/providers/{provider}/images/generations
```
የአቅራቢው ቅድመ ቅጥያ ከጎደለ በራስ-ሰር ይጨመራል። የማይዛመዱ ሞዴሎች `400` ይመልሳሉ።
---
## Files API
ለባች ግቤት/ውጤት እና በፋይል ዓላማ መሠረት ለሚደረጉ ሰቀላዎች OpenAI-ተኳሃኝ የፋይሎች መዳረሻ።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ------------------------ | --------------------------------------------------------------------------------------------------------- |
| POST | `/v1/files` | ፋይል ይስቀሉ (ባለብዙ ክፍል፦ `file`፣ `purpose`፣ `expires_after[anchor]`፣ `expires_after[seconds]`) — ከፍተኛው 512 MiB |
| GET | `/v1/files` | ለተረጋገጠው API ቁልፍ ፋይሎችን ይዘርዝሩ |
| GET | `/v1/files/[id]` | የፋይል ሜታዳታን ያግኙ |
| DELETE | `/v1/files/[id]` | ፋይል ይሰርዙ |
| GET | `/v1/files/[id]/content` | ጥሬውን የፋይል ይዘት በዥረት መልሰው ይላኩ |
**ማረጋገጫ፦** Bearer API ቁልፍ — ፋይሎች በ`getApiKeyRequestScope` አማካኝነት ለእያንዳንዱ API ቁልፍ ተለይተው ይገደባሉ።
---
## 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 ቁልፍ ተለይተው ይገደባሉ።
---
## 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 ያምጡ/ይፈትሹ — body በ`v1WebFetchSchema` ይረጋገጣል |
**ማረጋገጫ:** Bearer API ቁልፍ (`extractApiKey` + `isValidApiKey`)። ፖሊሲው በ`enforceApiKeyPolicy` ይተገበራል።
**ኮታን የሚያገናዝብ አማራጭ (#8297):** ግልጽ `provider` ካልተሰጠ፣ የአቅራቢዎች ስብስብ
(`firecrawl` → `jina-reader` → `tavily-search` → `tinyfish` → `nimble-search`) በቋሚ
የቅድሚያ ቅደም ተከተል (fill-first) ይሞከራል — የጥያቄ መጠኑ የተገደበ ነገር ግን የተዋቀረ አቅራቢ
ጥያቄውን ወዲያውኑ ከማቋረጥ ይልቅ ይታለፋል፤ እንዲሁም እንደገና ሊሞከር የሚችል/ከኮታ ጋር የተያያዘ upstream ውድቀት
(HTTP 429 ሁልጊዜ፤ ለFirecrawl/Tavily/TinyFish ኮታ-አይነት ነፃ ደረጃዎች 402/403 —
ለJina Reader ግን አይደለም፣ እንዲሁም ለተራ 400 የተሳሳተ ጥያቄ ፈጽሞ አይደለም) ጥያቄው በሚካሄድበት ጊዜ ወደ
ቀጣዩ ገና ያልተሞከረ እና ማረጋገጫ ያለው አቅራቢ ያልፋል። በስብስቡ ውስጥ ያሉ አቅራቢዎች በሙሉ
ሲያልቁ፣ endpoint ከቀድሞው አጠቃላይ `400` ይልቅ አንድ `429` (`Retry-After`
header ያለው) ይመልሳል። ግልጽ `provider` ሲጠየቅ፣ በድብቅ የሚደረግ አማራጭ **የለም** — የጥያቄ መጠኑ የተገደበ ወይም የወደቀ ግልጽ
አቅራቢ የራሱን ስህተት ያሳያል (የጥያቄ መጠኑ ከተገደበ `429`፣ አለበለዚያ የupstream
ሁኔታ)።
---
## WebSocket ዥረት
```bash
GET /v1/ws?handshake=1
```
የWebSocket upgrade handshakeን ያረጋግጣል እና የwire protocol ምሳሌ መልዕክቶችን (`request`፣ `cancel`) ይመልሳል። ትክክለኛዎቹ WS frames ከNext.js route table ውጭ በተካተተው WS server ይካሄዳሉ።
**ማረጋገጫ:** በhandshake ጊዜ Bearer API ቁልፍ።
### Responses API በWebSocket ላይ (codex ብቻ)
```bash
# ከHTTP API ጋር ተመሳሳይ host:port (ነባሪ 20128)፤ ግንኙነቱን upgrade ያድርጉ፦
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` transport አማካኝነት ወደ
`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/` prefix የሌለው)
OpenAI **Codex CLI** `supports_websockets = true` ሲሆን የmodel ስሙን በclient በኩል
ያረጋግጣል እና እንደ `codex/gpt-5.5` ያሉ **provider-prefixed ids ውድቅ ያደርጋል**
(`The 'codex/gpt-5.5' model is not supported when using Codex with
a ChatGPT account`)። **ባዶውን** id (ለምሳሌ `gpt-5.5`) ይላኩ። OmniRoute bridge
codex-only ስለሆነ፣ ወደ upstream tunnel ከማድረጉ በፊት ባዶ idን እንደ codex model
(`resolveCodexWsModelInfo`) እንደገና ይፈታል — ምንም እንኳን ባዶ
`gpt-5.5` በሌላ ሁኔታ በHTTP ላይ ወደ ሌላ አቅራቢ routing ቢደረግም።
#### OpenAI Codex CLIን ማዋቀር
WebSocket ድጋፍ ያለው custom provider ወደ `~/.codex/config.toml` በማከል Codex CLIን ወደ OmniRoute
ያመልክቱ (ነባር configን ላለመንካት የተለየ `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 ከዚህ ይመነጫል (በproduction https/wss ይጠቀሙ)
wire_api = "responses" # ከFeb 2026 ጀምሮ የሚደገፈው ብቸኛ እሴት
supports_websockets = true # Responses-over-WS transportን ያነቃል
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 upgrade ያደርጋል፣ እና 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` + token ያስፈልጋል) |
**ማረጋገጫ:** Bearer API ቁልፍ (`isAuthenticated`)።
---
## የራስ-አገልግሎት አጠቃቀም (`/api/usage/om-usage`)
ማንኛውም API ቁልፍ **የራሱን** አጠቃቀም እና ኮታዎች ማንበብ ይችላል — የአስተዳደር ማረጋገጫ አያስፈልግም። ይህ ደንበኛ
(CLI፣ የOmniCopilot ፓነል) ለቁልፍ ባለቤት ወጪውን ለማሳየት የሚጠቀምበት endpoint ነው።
```bash
# የጽሑፍ ቅርጽ (ታሪካዊው ውል — ለተርሚናል ተራ ጽሑፍ)
curl -H "Authorization: Bearer <your-api-key>" \
http://localhost:20128/api/usage/om-usage
# የተዋቀረ ቅርጽ — UI የሚጠቀምበት
curl -H "Authorization: Bearer <your-api-key>" \
"http://localhost:20128/api/usage/om-usage?format=json"
```
ቁልፉ **`allowUsageCommand`** የነቃለት መሆን አለበት (በነባሪ የጠፋ ነው — የዳሽቦርዱ API-ቁልፍ
አስተዳዳሪ ለእያንዳንዱ ቁልፍ ያበራዋል ወይም ያጠፋዋል)። ያለዚህ endpoint የ`403` ምላሽ ይሰጣል።
ጠሪው ከመከልከል ምላሽ ላይ የውሂብ መስክ በፍጹም እንዳያነብ፣ `?format=json` ሁኔታውን የሚለይ ቅርጽ ይመልሳል።
ሲሳካ፦
```jsonc
{
"allowed": true,
// ቁልፉ ለእያንዳንዱ ቁልፍ የአጠቃቀም ገደቦችን (ዕለታዊ/ሳምንታዊ USD) ሲመርጥ ብቻ ይገኛል፦
"personal": {
"dailySpentUsd": 1.25,
"dailyLimitUsd": 5,
"dailyResetAtIso": "…",
"weeklySpentUsd": 8,
"weeklyLimitUsd": 20,
"weeklyResetAtIso": "…" /* … */,
},
// የተመረጠው የአቅራቢ ኮታ ቅጽበታዊ ገጽታ፣ ወይም እስካሁን ምንም ካልተሸጎጠ null፦
"provider": {
"connectionId": "…",
"provider": "claude",
"plan": "…",
"quotas": {/* … */},
},
// UI በርካታ አቅራቢዎችን ጎን ለጎን እንዲያሳይ፣ የእያንዳንዱ ግንኙነት ቅጽበታዊ ገጽታ፦
"providers": [
{ "connectionId": "…", "provider": "claude" /* … */ },
{ "provider": "codex" /* … */ },
],
}
```
በመከልከል ጊዜ (`401` ልክ ያልሆነ ቁልፍ / `403` ያልተፈቀደ) ያው route
`{ "allowed": false, "error": { "message": "…" } }` ይመልሳል — ያለ ነገር ግን ባዶ የሆነ `personal`/`provider`
(ቁልፉ ተፈቅዷል፣ እስካሁን ምንም አልታወቀም) ከመከልከል የተለየ ሁኔታ ሲሆን፣ እነዚህን የሚለየው የJSON ቅርጽ ብቻ
ነው።
**ማረጋገጫ:** በ`isValidApiKey` የተረጋገጠ የጠሪው የራሱ Bearer API ቁልፍ — ይህ ከ`requireManagementAuth` በስተጀርባ እንደቆየው
የአስተዳደር በይነገጽ (`/api/keys/…`) _አይደለም_።
---
## ሴማንቲክ መሸጎጫ
```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 ምላሹን **ወደ upstream ጥሪ ሳያደርግ**
ከመሸጎጫ ያቀርባል፤ ስለዚህ ሪፖርት የሚደረገው `X-OmniRoute-Response-Latency` ወደ ዜሮ የቀረበ ነው
(የመጀመሪያው upstream ምላሽ ጊዜ ምንም ይሁን)። ለምላሽ ጊዜ ስሱ የሆኑ ደንበኞች
(ቤንችማርክ ማድረግ፣ p50/p99 ክትትል) የ`X-OmniRoute-Cache-Latency` ምላሽ ራስጌን
መፈተሽ አለባቸው፦
| እሴት | ትርጉም |
| ----------- | ------------------------------------------------- |
| `synthetic` | ምላሹ ከመሸጎጫ ቀርቧል፤ የምላሽ ጊዜው እውነተኛ የupstream ጊዜ አይደለም |
| _(የለም)_ | ከእውነተኛ የupstream ጥሪ የመጣ ምላሽ |
### ለእያንዳንዱ ቁልፍ መሸጎጫን ማለፍ
API ቁልፎች `cacheDefaultMode` በመጠቀም የሴማንቲክ መሸጎጫ ንባቦችን ላለመጠቀም መምረጥ ይችላሉ፦
| እሴት | ባህሪ |
| -------- | ------------------------------------------ |
| `legacy` | መደበኛ የመሸጎጫ ባህሪ (ነባሪ) |
| `bypass` | የመሸጎጫ ፍለጋን ሙሉ በሙሉ ይዝለሉ፤ ሁልጊዜ upstream ይጠቀሙ |
ቁልፍ ሲፈጠር (`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*` | የተለያዩ | የአቅራቢ ኖድ አስተዳደር |
| `/api/provider-models` | GET/POST/PATCH/DELETE | ብጁ ሞዴሎች (ማከል፣ ማዘመን፣ መደበቅ/ማሳየት፣ መሰረዝ) |
### OAuth ፍሰቶች
| መዳረሻ | ዘዴ | መግለጫ |
| -------------------------------- | ----- | ----------------- |
| `/api/oauth/[provider]/[action]` | የተለያዩ | ለአቅራቢው የተለየ OAuth |
### ማስተላለፊያ እና ውቅር
| መዳረሻ | ዘዴ | መግለጫ |
| --------------------- | -------- | ---------------------- |
| `/api/models/alias` | GET/POST | የሞዴል ተለዋጭ ስሞች |
| `/api/models/catalog` | GET | ሁሉም ሞዴሎች በአቅራቢ + በዓይነት |
| `/api/combos*` | የተለያዩ | የጥምረት አስተዳደር |
| `/api/keys*` | የተለያዩ | የAPI ቁልፍ አስተዳደር |
| `/api/pricing` | GET | የሞዴል ዋጋ አወጣጥ |
### አጠቃቀም እና ትንታኔ
| Endpoint | Method | Description |
| -------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/usage/history` | GET | የአጠቃቀም ታሪክ |
| `/api/usage/logs` | GET | የአጠቃቀም ምዝግብ ማስታወሻዎች |
| `/api/usage/request-logs` | GET | የጥያቄ ደረጃ ምዝግብ ማስታወሻዎች |
| `/api/usage/[connectionId]` | GET | የእያንዳንዱ ግንኙነት አጠቃቀም |
| `/api/usage/token-limits` | GET/POST/DELETE | የእያንዳንዱ API ቁልፍ የቶከን ገደብ በጀቶች |
| `/api/usage/model-latency-stats` | GET | ተንከባላይ የእያንዳንዱ አቅራቢ/ሞዴል የመዘግየት ጊዜ ድምር ስታቲስቲክስ (አማካይ/p50/p95/p99፣ የስኬት መጠን)፤ ማጣሪያዎች፦ `windowHours`/`minSamples`/`maxRows`/`provider`/`model` (#6873) |
| `/api/usage/cache-health` | GET | በ`call_logs` ላይ የተመሠረተ የፕሮምፕት መሸጎጫ ጤንነት ማጠቃለያ — የመጻፍ/ማንበብ ሬሾ፣ p50/p90/p99 የመጻፍ መጠን ስርጭት፣ የከባድ ጽሑፍ ትኩረት፣ በሞዴል የተከፋፈለ ውጤት፣ እና የ`healthy`/`degraded`/`thrash`/`no-data` ፍርድ፤ የመጠይቅ መለኪያዎች `range` (`1h`\|`24h`\|`7d`\|`30d`፣ ነባሪ `24h`) እና አማራጭ `model` (#8827) |
### ቅንብሮች
| Endpoint | Method | Description |
| ------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/api/settings` | GET/PUT/PATCH | አጠቃላይ ቅንብሮች |
| `/api/settings/proxy` | GET/PUT | የአውታረ መረብ ፕሮክሲ ውቅር |
| `/api/settings/proxy/test` | POST | የፕሮክሲ ግንኙነትን ይፈትሻል |
| `/api/settings/ip-filter` | GET/PUT | የIP ፈቃድ ዝርዝር/እገዳ ዝርዝር |
| `/api/settings/thinking-budget` | GET/PUT | የማሰብ/ምክንያታዊ ትንተና **ጥያቄ** እንደገና የመጻፍ ሁነታ (እንዳለ ማሳለፍ / በራስ-ሰር ማስወገድ / ብጁ / መላመድ የሚችል)። ከመጭመቅ ነፃ ነው። [THINKING_BUDGET.md](../guides/THINKING_BUDGET.md)ን ይመልከቱ። |
| `/api/settings/system-prompt` | GET/PUT | ዓለም አቀፍ የስርዓት ፕሮምፕት |
| `/api/settings/compression` | GET/PUT | ዓለም አቀፍ የመጭመቂያ ውቅር |
| `/api/settings/purge-request-history` | POST | የጥያቄ ምዝግብ ረድፎችን እና የአካባቢያዊ ጥሪ ምዝግብ ቅርሶችን ያጸዳል |
### ዐውድ እና መጭመቅ
| Endpoint | Method | Description |
| -------------------------------------- | -------------- | ------------------------------------------------------------------ |
| `/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 | Description |
| ------------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/api/sessions` | GET | ንቁ ክፍለ-ጊዜዎችን መከታተል |
| `/api/rate-limits` | GET | የእያንዳንዱ መለያ የፍጥነት ገደቦች |
| `/api/monitoring/health` | GET | የጤና ምርመራ + የአቅራቢዎች ማጠቃለያ (`catalogCount`፣ `configuredCount`፣ `activeCount`፣ `monitoredCount`)። የአስተዳደር እይታው `credentialHealth`ን ያካትታል፦ የprobe-cache scalar እሴቶች፣ `failed>0` ሲሆን `failedConnections`፣ እና `staleDbNonOkCount` (የSQLite ቋሚ `test_status`፣ gauge አይደለም)። [MONITORING_GUIDE.md](../ops/MONITORING_GUIDE.md#credentialhealth-probe-cache-vs-sqlite-test_status)ን ይመልከቱ። |
| `/api/cache/stats` | GET/DELETE | የcache ስታቲስቲክስ / ማጽዳት |
| `/api/modality-bridge/stats` | GET | በማህደረ ትውስታ ውስጥ ያሉ `attempts`፣ ስኬቶች/`bridged`፣ ውድቀቶች፣ የcache hits፣ `totalLatencyMs`፣ `latencySamples`፣ በናሙና ብዛት የተካፈለ `averageLatencyMs`፣ እና የመጨረሻ አጠቃቀም ጊዜ (ዳግም ሲጀመር ይሰረዛል፤ የአስተዳደር ማረጋገጫ ያስፈልጋል) |
| `/api/modality-bridge/video/runtime` | GET | ከአስተዳደር ማረጋገጫ/probe በፊት ጥብቅ የታመነ-loopback ምርመራ፤ የጸዱ የFFmpeg/ffprobe ተገኝነት እና ስሪቶች (no-store) |
| `/api/modality-bridge/video/extract` | POST | ውስጣዊ፣ ማረጋገጫ ያለው የታመነ-loopback ባይት ደላላ፤ 50 MiB ግብዓት፣ የተገደበ queue/32 MiB ውጤት፣ `503` የአቅም ችግር፣ `499` ግንኙነት መቋረጥ፣ `504` የጊዜ ገደብ፤ ይፋዊ የupload 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 ፋይል ይሰቅላል |
| `/api/db-backups/exportAll` | GET | ሙሉ ምትኬውን እንደ .tar.gz ማህደር ያወርዳል |
### የደመና ማመሳሰል
| Endpoint | Method | መግለጫ |
| ---------------------- | ------ | ---------------- |
| `/api/sync/cloud` | የተለያዩ | የደመና ማመሳሰል ክንውኖች |
| `/api/sync/initialize` | POST | ማመሳሰልን ያስጀምራል |
| `/api/cloud/*` | የተለያዩ | የደመና አስተዳደር |
### ቱነሎች
| 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 | በቀሪ ጊዜ የተደረደሩ ንቁ የእያንዳንዱ-(provider, connection, model) እገዳዎችን ይዘረዝራል |
| `/api/resilience/model-cooldowns` | DELETE | የሞዴል እገዳን ያጸዳል — አካል `{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 |
እነዚህ endpoints ከአገርኛው Gemini SDK ጋር ተኳሃኝነትን ለሚጠብቁ ደንበኞች የGeminiን API ቅርጸት ያንጸባርቃሉ።
### ውስጣዊ / የስርዓት APIዎች
| የመዳረሻ ነጥብ | ዘዴ | መግለጫ |
| ------------------------ | ---- | ------------------------------------------- |
| `/api/init` | GET | የመተግበሪያ ማስጀመሪያ ማረጋገጫ (በመጀመሪያ አጠቃቀም ላይ ይውላል) |
| `/api/tags` | GET | ከOllama ጋር ተኳሃኝ የሞዴል መለያዎች (ለOllama ደንበኞች) |
| `/api/restart` | POST | አገልጋዩ ያለችግር እንዲጀመር ማስነሳት |
| `/api/shutdown` | POST | አገልጋዩ ያለችግር እንዲዘጋ ማስነሳት |
| `/api/system/env/repair` | POST | የOAuth አቅራቢ የአካባቢ ተለዋዋጮችን መጠገን |
> **ማስታወሻ፦** እነዚህ የመዳረሻ ነጥቦች በስርዓቱ ውስጥ ለውስጣዊ አገልግሎት ወይም ከOllama ደንበኛ ጋር ለመጣጣም ያገለግላሉ። በተለምዶ በዋና ተጠቃሚዎች አይጠሩም።
### የOAuth አካባቢ ጥገና _(v3.6.1+)_
```bash
POST /api/system/env/repair
Content-Type: application/json
{
"provider": "claude-code"
}
```
ለአንድ የተወሰነ አቅራቢ የጠፉ ወይም የተበላሹ የOAuth አካባቢ ተለዋዋጮችን ይጠግናል። የሚከተለውን ይመልሳል፦
```json
{
"success": true,
"repaired": ["CLAUDE_CODE_OAUTH_CLIENT_ID", "CLAUDE_CODE_OAUTH_CLIENT_SECRET"],
"backupPath": "/home/user/.omniroute/backups/env-repair-2026-04-11.bak"
}
```
---
## የድምፅ ጽሑፍ ቅጂ
```bash
POST /v1/audio/transcriptions
Authorization: Bearer your-api-key
Content-Type: multipart/form-data
```
የተዋቀረ ማንኛውንም የSTT አቅራቢ በመጠቀም የድምፅ ፋይሎችን ወደ ጽሑፍ ይቀይሩ። የመጀመሪያው የዱካ
ክፍል ቤተኛውን አቅራቢ (`openai/…`፣ `deepgram/…`) ይመርጣል። የሌላ አቅራቢን ሞዴል
እንደገና የሚያቀርቡ ጌትዌዮች ሙሉ መለያ
(`openrouter/deepgram/nova-3`) ይጠቀማሉ።
**ጥያቄ፦**
```bash
curl -X POST http://localhost:20128/v1/audio/transcriptions \
-H "Authorization: Bearer your-api-key" \
-F "file=@recording.mp3" \
-F "model=openai/whisper-1"
```
**ምላሽ፦**
```json
{
"text": "ሰላም፣ ይህ ወደ ጽሑፍ የተቀየረው የድምፅ ይዘት ነው።",
"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":"ሰላም"}]}'
```
ማስታወሻዎች፦
- ቶከን የያዙት ተለዋጭ ስሞች እንደ `/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
}
# የቶከን ገደብን በመለያው ሰርዝ
DELETE /api/usage/token-limits?id=tl-abc
```
> **የSchema ማስታወሻዎች** (`setTokenLimitSchema`)፦ `apiKeyId` እና `scopeType` (`model` | `provider` | `global`) ያስፈልጋሉ። `scopeType` `global` ካልሆነ በስተቀር `scopeValue` ያስፈልጋል (ለምሳሌ፣ ለ`model` ወሰን የሞዴል መለያ፣ ለ`provider` ወሰን የአቅራቢ መለያ)። `tokenLimit` አዎንታዊ ኢንቲጀር መሆን አለበት (ከሕብረቁምፊ ይቀየራል)። አማራጭ፦ `id` (ለመፍጠር አያካትቱት፣ ለማዘመን ያቅርቡት)፣ `resetInterval` (`daily` | `weekly` | `monthly`፣ ነባሪው `monthly`)፣ `resetTime` (`HH:MM`)፣ `enabled` (ነባሪው `true`)። የ`GET` ምላሾች እያንዳንዱን ገደብ በ`tokensUsed`፣ `remaining`፣ `windowStart`፣ `periodStartAt` እና `nextResetAt` ያበለጽጋሉ። ይህ የአስተዳደር ደረጃ ያለው endpoint ነው (ማረጋገጫው በauthz pipeline ማዕከላዊ ሁኔታ ይተገበራል)።
## የጥያቄ ሂደት
1. ደንበኛው ጥያቄውን ወደ `/v1/*` ይልካል
2. የRoute handler `handleChat`፣ `handleEmbedding`፣ `handleAudioTranscription` ወይም `handleImageGeneration`ን ይጠራል
3. ሞዴሉ ይፈታል (ቀጥተኛ provider/model ወይም alias/combo)
4. የመለያ ተገኝነት ማጣሪያን በመጠቀም ማረጋገጫዎች ከአካባቢያዊ DB ይመረጣሉ
5. ለውይይት፦ `handleChatCore` የsemantic/signature cacheን ይፈትሻል እና የcombo compression ቅንብሮችን ይፈታል
6. ሲነቃ፣ ከprovider translation በፊት ቀድሞ የሚደረግ compression ይከናወናል (`lite`፣ Caveman፣ RTK ወይም stacked)
7. የProvider executor ጥያቄውን ወደ upstream ይልካል
8. ምላሹ ወደ ደንበኛው ቅርጸት ተመልሶ ይተረጎማል (ውይይት) ወይም እንዳለ ይመለሳል (embeddings/images/audio)
9. አጠቃቀም፣ የcompression analytics እና የጥያቄ ምዝግብ ማስታወሻዎች ይመዘገባሉ
10. ስህተቶች ሲከሰቱ fallback በcombo ደንቦች መሠረት ይተገበራል
ሙሉ የአርክቴክቸር ማጣቀሻ፦ [`ARCHITECTURE.md`](../architecture/ARCHITECTURE.md)
---
## የCombo አስተዳደር
ከፍተኛ ደረጃ ያላቸው የrouting combos (ቀደም ሲል በ`/api/combos*` ሥር ተጠቃለው የቀረቡ) ከሞዴል መለያ ጥለት ጋር 1:1 ሊመደቡ ይችላሉ፤ ይህም የOpenAI-ቅጥ ሞዴል መለያን በግልጽነት ወደ combo ማዞር ያስችላል።
| ዘዴ | ዱካ | መግለጫ |
| ------ | -------------------------------- | --------------------------------------------------------------------------- |
| GET | `/api/model-combo-mappings` | ሁሉንም የmodel→combo ምደባዎች ዘርዝር |
| POST | `/api/model-combo-mappings` | ምደባ ፍጠር — የጥያቄ አካል፦ `{pattern, comboId, priority?, enabled?, description?}` |
| GET | `/api/model-combo-mappings/[id]` | አንድ ምደባ አምጣ |
| PUT | `/api/model-combo-mappings/[id]` | ያለውን ምደባ መስኮች አዘምን |
| DELETE | `/api/model-combo-mappings/[id]` | ምደባ አስወግድ |
**ማረጋገጫ፦** የአስተዳደር session/API key (`requireManagementAuth`)።
---
## Webhooks
ለOmniRoute ክስተቶች (የጥያቄ ማጠናቀቅ፣ የኮታ ማለቅ፣ የቁልፍ ማዞር፣ ወዘተ) የወጪ webhook ምዝገባዎች።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ------------------------- | ----------------------------------------------------------------------- |
| GET | `/api/webhooks` | Webhook-ዎችን ይዘርዝሩ (ሚስጥሮች ወደ `<prefix>...` ተሸፍነው ይታያሉ) |
| POST | `/api/webhooks` | Webhook ይፍጠሩ — የጥያቄ አካል፦ `{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` | የሙከራ payload ወደ webhook URL ይላኩ እና የማድረሻ ሁኔታውን ይመልሱ |
**ማረጋገጫ፦** የአስተዳደር session/API key (`requireManagementAuth`)።
---
## የተመዘገቡ ቁልፎች (ራስ-ሰር አስተዳደር)
በየቀኑ/በየሰዓቱ ኮታዎች በመጠቀም፣ የራስ-ሰር ቁልፍ አስተዳደር ንዑስ-ስርዓቱ ደጋፊ provider/accountን በመጠቀም API keysን እንዲያወጣና እንዲያዞር ይጠቀምባቸዋል።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/v1/registered-keys` | የተመዘገቡ ቁልፎችን ይዘርዝሩ (የተሸፈነ prefix ብቻ) |
| POST | `/api/v1/registered-keys` | አዲስ የተመዘገበ ቁልፍ ያውጡ — የጥያቄ አካል፦ `{name, provider?, accountId?, idempotencyKey?, expiresAt?, dailyBudget?, hourlyBudget?}`። ጥሬ ቁልፉን **አንድ ጊዜ** ብቻ ይመልሳል። በኮታ ምክንያት ውድቅ ሲደረግ `429` ይመልሳል። |
| GET | `/api/v1/registered-keys/[id]` | የተመዘገበ ቁልፍ metadata ያግኙ (ጥሬ ይዘት የለም) |
| DELETE | `/api/v1/registered-keys/[id]` | የተመዘገበ ቁልፍ ይሻሩ |
| POST | `/api/v1/registered-keys/[id]/revoke` | ግልጽ የስረዛ endpoint (ከDELETE ጋር ተመሳሳይ ውጤት) |
**ማረጋገጫ፦** Bearer API key (`isAuthenticated`)። እንዲሁም `/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` ከተዋቀረ ሁኔታውን ከላይኛው cloud agent ጋር በተመሳሰለ ሁኔታ ያድሳል |
| POST | `/api/v1/agents/tasks/[id]` | የተለየ ድርጊት፦ `{action: "approve"}`, `{action: "message", message}` ወይም `{action: "cancel"}` |
| DELETE | `/api/v1/agents/tasks/[id]` | በid የተወሰነ ተግባር ሰርዝ |
> **ማረጋገጫ፦** በእያንዳንዱ ዘዴ ላይ የአስተዳደር ማረጋገጫ ያስፈልጋል (`requireCloudAgentManagementAuth`)። ከv3.8.0 በፊት እነዚህ ያለማረጋገጫ ይገኙ ነበር — ለዚህ መሰረታዊ ለውጥ commit `588a0333`ን ይመልከቱ።
```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":"..."}}'
```
---
## የአስተዳደር Proxies
ለproviders፣ accounts ወይም በአጠቃላይ ሊመደቡ የሚችሉ ወደ ውጭ የሚላኩ HTTP(S)/SOCKS proxies።
| ዘዴ | ዱካ | መግለጫ |
| ------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| GET | `/api/v1/management/proxies` | proxiesን ዘርዝር (`?id=` ሲጨመር አንዱን ይመልሳል፤ `?id=&where_used=1` ሲጨመር የምደባ ግራፉን ይመልሳል) |
| POST | `/api/v1/management/proxies` | proxy ፍጠር — bodyው በ`createProxyRegistrySchema` ይረጋገጣል |
| PATCH | `/api/v1/management/proxies` | proxy አዘምን — bodyው በ`updateProxyRegistrySchema` ይረጋገጣል (`id` ያስፈልጋል) |
| DELETE | `/api/v1/management/proxies?id=...&force=1` | proxy ሰርዝ (ምደባዎችን ለማላቀቅ `force=1`ን ይጠቀሙ) |
| GET | `/api/v1/management/proxies/assignments` | ምደባዎችን ዘርዝር — በ`proxy_id`, `scope`, `scope_id` ሊጣራ ይችላል፤ ለአንድ connection ንቁ proxyውን ለመፍታት `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` | በተወሰነ ጊዜ መስኮት ውስጥ የተጠቃለለ የproxy ጤንነት (የስኬት/ውድቀት ብዛት፣ latency) |
**ማረጋገጫ፦** በእያንዳንዱ route ላይ የአስተዳደር 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`ን ይደግፋል፤ ተመሳሳይ መስኮች በዳሽቦርድ → ቅንብሮች → የመቋቋም ችሎታ ውስጥም ይገኛሉ።
```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 የተረጋገጠ፦ `{content, key, type?, sessionId?, apiKeyId?, metadata?, expiresAt?}` |
| GET | `/api/memory/[id]` | አንድ ማህደረ ትውስታ ሰርስር |
| DELETE | `/api/memory/[id]` | ማህደረ ትውስታ ሰርዝ |
| GET | `/api/memory/health` | የማህደረ ትውስታ ንዑስ ስርዓት ጤንነት (የDB ግንኙነት፣ የembeddings ጀርባ ስርዓት፣ የvector index ሁኔታ) |
**ማረጋገጫ፦** የአስተዳደር ክፍለ ጊዜ/API ቁልፍ (`requireManagementAuth`)። `type` enum፦ `FACTUAL`, `EPISODIC`, `SEMANTIC`, `PROCEDURAL` (`src/lib/memory/types.ts` ውስጥ `MemoryType`ን ይመልከቱ)።
---
## MCP አገልጋይ
OmniRoute 3 የማጓጓዣ ዘዴዎች (stdio, SSE, streamable-http) እና ወሰን ያላቸው መሣሪያዎች ያሉትን የተካተተ Model Context Protocol አገልጋይ ይዞ ይመጣል። ከታች ያሉት የዳሽቦርድ መዳረሻዎች የሁኔታ/ኦዲት ውሂብን ያነባሉ እና የHTTP ማጓጓዣዎችን በውክልና ያስተላልፋሉ።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------ | -------------------- |
| GET | `/api/mcp/status` | የልብ ምት፣ ማጓጓዣ፣ የመስመር ላይ ሁኔታ፣ የመጨረሻ ጥሪ፣ ቀዳሚ መሣሪያዎች፣ የ24 ሰዓት የስኬት መጠን |
| GET | `/api/mcp/tools` | የMCP መሣሪያዎች ዝርዝር ከ`name`, `description`, `scopes`, `phase`, `auditLevel`, `sourceEndpoints` ጋር |
| GET | `/api/mcp/sse` | ለSSE ማጓጓዣው ክፍት SSE ዥረት (MCP ከተሰናከለ ወይም ማጓጓዣው ካልተዛመደ `503` ይመልሳል) |
| POST | `/api/mcp/sse` | በSSE ማጓጓዣው ላይ JSON-RPC ፍሬም ላክ |
| GET | `/api/mcp/stream` | የStreamable HTTP ማጓጓዣውን SSE ጎን ክፈት (በአገልጋዩ የሚጀመሩ መልዕክቶች) |
| POST | `/api/mcp/stream` | በStreamable HTTP ማጓጓዣው ላይ JSON-RPC ፍሬም ላክ |
| DELETE | `/api/mcp/stream` | የStreamable HTTP ክፍለ ጊዜን ጨርስ |
| GET | `/api/mcp/audit` | የኦዲት ምዝግብ መዝገብን ጠይቅ — `?limit=`, `?offset=`, `?tool=`, `?success=true | false`, `?apiKeyId=` |
| GET | `/api/mcp/audit/stats` | የተጠቃለሉ የኦዲት ስታቲስቲክሶች (ጠቅላላ ቁጥሮች፣ የስኬት መጠን፣ አማካይ ቆይታ፣ ቀዳሚ መሣሪያዎች) |
**ማረጋገጫ፦** የ`sse`/`stream` ማጓጓዣዎች ለMCP የተለየውን የማረጋገጫ ገጽታ ያከብራሉ (`mcp` ወሰን ያለው Bearer API ቁልፍ)፤ የ`status`/`tools`/`audit*` መንገዶች ከዳሽቦርዱ ሊነበቡ ይችላሉ (የዳሽቦርዱ አስተናጋጅ ላይ ከመድረስ ባለፈ ተጨማሪ ማረጋገጫ አያስፈልግም)።
> ሁለቱም የHTTP ማጓጓዣዎች በ`settings.mcpEnabled` እና `settings.mcpTransport` የተገደቡ ናቸው — የማጓጓዣ አለመዛመድ `400`ን ይመልሳል፣ MCP የተሰናከለበት ሁኔታ `503`ን ይመልሳል።
---
## A2A አገልጋይ
OmniRoute የ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` | አመክንዮአዊ የሞዴል idን የአካባቢውን የማዞሪያ ሰንጠረዥ በመጠቀም ወደ ተወሰነ አቅራቢ/ሞዴል ይፈታል |
| GET | `/api/cloud/models/alias` | ለደመና ማመሳሰል የሚቀርቡ የሞዴል ተለዋጭ ስሞችን ይዘረዝራል |
| GET | `/api/assess` | የቅርብ ጊዜዎቹን የዳሰሳ ምደባዎች (በየአቅራቢው/ሞዴሉ) ያነባል |
| POST | `/api/assess` | ዳሰሳ ያካሂዳል — ይዘት፦ `{scope: {type:"all"} | {type:"provider", providerId} | {type:"model", modelId}, trigger?}` |
| GET | `/api/evals` | አብረው የተካተቱ የግምገማ ስብስቦችን + የቅርብ ጊዜ አሂዶችን ይዘረዝራል |
| POST | `/api/evals` | የግምገማ አሂድን ያስጀምራል |
| POST | `/api/evals/suites` | ብጁ የግምገማ ስብስብ ይፈጥራል — ይዘቱ በ`evalSuiteSaveSchema` ይረጋገጣል |
| GET | `/api/evals/suites/[id]` | ብጁ የግምገማ ስብስብን ያመጣል |
**ማረጋገጫ፦** `/api/cloud/auth` የBearer ቁልፍን በቀጥታ ያረጋግጣል፤ ሌሎቹ `/api/cloud/*`፣ `/api/evals/*` እና `/api/assess` መንገዶች የአስተዳደር ክፍለ ጊዜ/API ቁልፍ ያስፈልጋቸዋል። `/api/assess` POST የተለየ-ዩኒየን የወሰን መርሃግብር ያለውን `validateBody` ይጠቀማል።
---
## ACP (Agent Client Protocol) አስተዳደር
እንደ ልጅ ሂደቶች። እነዚህ የመጨረሻ ነጥቦች የACP ወኪል ማግኘትን እና ብጁ ወኪል
ምዝገባን ያስተዳድራሉ።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | `/api/acp/agents` | ሁሉንም የታወቁ CLI ወኪሎች (አብሮገነብ + ብጁ) ከመጫን ሁኔታ፣ ስሪት እና binary ጋር ይዘረዝራል |
| POST | `/api/acp/agents` | ብጁ ACP ወኪል ይመዘግባል ወይም መሸጎጫውን ያድሳል — body: `{id, name, binary, versionCommand, providerAlias, spawnArgs, protocol}` ወይም `{action: "refresh"}` |
| DELETE | `/api/acp/agents` | ብጁ ACP ወኪልን ያስወግዳል — query param: `?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
}
```
**ማረጋገጫ:** የአስተዳደር ክፍለ ጊዜ (የdashboard `auth_token` cookie) ወይም
የአስተዳደር ወሰን ያለው API ቁልፍ ያስፈልጋል።
ለሙሉ ዝርዝሮች [ACP Framework](../frameworks/ACP.md)ን ይመልከቱ።
---
## ትንታኔ እና ታዛቢነት
ማዘዋወርን፣ መጭመቅን እና የአቅራቢ ብዝሃነትን ለመከታተል የእውነተኛ ጊዜ ትንታኔ የመጨረሻ ነጥቦች። እነዚህ ለ`/dashboard/analytics/*` ገጾች
ኃይል ይሰጣሉ።
### የራስ-ሰር ማዘዋወር ትንታኔ
| ዘዴ | ዱካ | መግለጫ |
| --- | ------------------------------------ | -------------------------------------------------------------------------- |
| GET | `/api/analytics/auto-routing` | የተጠቃለሉ የራስ-ሰር ማዘዋወር ስታቲስቲክስ፦ አጠቃላይ ጥሪዎች፣ የስትራቴጂ ስርጭት፣ የደረጃ ስርጭት፣ ዋና አቅራቢዎች |
| GET | `/api/analytics/auto-routing?days=7` | በጊዜ መስኮት የተገደቡ ስታቲስቲክስ (ነባሪው 24h) |
**የምላሽ ምሳሌ**:
```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` | የተጠቃለሉ የመጭመቅ ስታቲስቲክስ፦ የተቆጠቡ tokens፣ የቁጠባ %፣ የሁነታ ስርጭት፣ የengine አጠቃቀም |
**የምላሽ ምሳሌ**:
```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 entropy ላይ የተመሠረተ የብዝሃነት ክትትል፦ የአቅራቢዎችን ስርጭት በመለካት ነጠላ የብልሽት ነጥቦችን ይከላከላል |
**የምላሽ ምሳሌ**:
```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 ከትራፊኩ 40% ይይዛል — ብዝሃነትን መጨመር ያስቡበት"]
}
```
**ማረጋገጫ:** የአስተዳደር ክፍለ ጊዜ ወይም የአስተዳደር ወሰን ያለው API ቁልፍ ያስፈልጋል።
---
## የአስተዳዳሪ ክዋኔዎች
ለክወና አስተዳደር የሚያገለግሉ ለአስተዳዳሪዎች ብቻ የተፈቀዱ መጨረሻ ነጥቦች።
| ዘዴ | ዱካ | መግለጫ |
| ---- | ------------------------ | ----------------------------------------------------------------------------------------- |
| GET | `/api/admin/concurrency` | የአሁኑን የትይዩ ክወና ገደቦች ያንብቡ (አጠቃላይ + ለእያንዳንዱ አቅራቢ) |
| POST | `/api/admin/concurrency` | የትይዩ ክወና ገደቦችን ያዘምኑ — የጥያቄ ይዘት፦ `{global?: number, perProvider?: Record<string, number>}` |
**ማረጋገጫ፦** የአስተዳዳሪ ወሰን ያለው የአስተዳደር ክፍለ ጊዜ ያስፈልጋል።
---
## የCLI መሣሪያዎች አስተዳደር
ከOmniRoute ጋር የሚዋሃዱ የCLI መሣሪያዎችን (antigravity፣ chipotle፣ 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 ብጁ GPTs ጋር ተመሳሳይ፣ ነገር ግን ለወኪሎች)።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ---------------------------- | --------------------------------------------------------------------------------- |
| GET | `/api/agent-skills` | ሁሉንም የወኪል ክህሎቶች ይዘርዝሩ (አብረው የተካተቱ + ብጁ) |
| GET | `/api/agent-skills/[id]` | የተወሰነ የወኪል ክህሎት ያግኙ |
| POST | `/api/agent-skills` | ብጁ የወኪል ክህሎት ይፍጠሩ — የጥያቄ ይዘት፦ `{name, description, prompt, model?, temperature?}` |
| PUT | `/api/agent-skills/[id]` | ብጁ የወኪል ክህሎትን ያዘምኑ |
| DELETE | `/api/agent-skills/[id]` | ብጁ የወኪል ክህሎትን ይሰርዙ |
| GET | `/api/agent-skills/[id]/raw` | ጥሬ ጥያቄን + ሜታዳታን ያግኙ (ያለ ማስኬድ) |
| POST | `/api/agent-skills/generate` | ከተፈጥሯዊ ቋንቋ መግለጫ አዲስ ክህሎትን በAI ያመንጩ |
**ማረጋገጫ፦** የአስተዳደር ክፍለ ጊዜ ወይም በአስተዳደር የተወሰነ API ቁልፍ ያስፈልጋል።
---
## መሸጎጫ አስተዳደር
የፍቺ መሸጎጫውን እና የማመዛዘኛ መሸጎጫውን ያስተዳድሩ።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ---------------------- | ------------------------------------------------------------------------------------------------- |
| GET | `/api/cache` | የመሸጎጫ አጠቃላይ እይታ፦ ጠቅላላ ግቤቶች፣ የመገኘት መጠን፣ በዲስክ ላይ ያለው መጠን |
| GET | `/api/cache/entries` | የተሸጎጡ ግቤቶችን ይዘርዝሩ (ከገጽ ክፍፍል ጋር) |
| DELETE | `/api/cache/entries` | የመሸጎጫ ግቤቶችን ይሰርዙ (በጥያቄ መለኪያዎች ያጣሩ) |
| GET | `/api/cache/stats` | ዝርዝር የመሸጎጫ ስታቲስቲክስ (ለእያንዳንዱ አቅራቢ፣ ለእያንዳንዱ ሞዴል) |
| GET | `/api/cache/reasoning` | የማመዛዘኛ መሸጎጫ ሁኔታ (ማመዛዘንን እንደገና ለማጫወት) |
| DELETE | `/api/cache/reasoning` | የማመዛዘኛ መሸጎጫውን ያጽዱ — የጥያቄ መለኪያዎች፦ `?toolCallId=<id>` (ነጠላ) ወይም `?provider=<p>` ወይም ያለ መለኪያዎች (ሁሉም) |
**ማረጋገጫ፦** የአስተዳደር ክፍለ-ጊዜ ያስፈልጋል።
---
## የማህደረ ትውስታ ሥርዓት
ቋሚ ማህደረ ትውስታን (FTS5 + የቬክተር ውክልናዎች) ያስተዳድሩ።
| ዘዴ | ዱካ | መግለጫ |
| ------ | ------------------ | ----------------------------------------------------------------------- |
| GET | `/api/memory` | የማህደረ ትውስታ ግቤቶችን ይዘርዝሩ (በወሰን፣ ዓይነት፣ የፍለጋ ጥያቄ ያጣሩ) |
| POST | `/api/memory` | አዲስ የማህደረ ትውስታ ግቤት ይፍጠሩ — የጥያቄ አካል፦ `{scope, type, content, metadata?}` |
| GET | `/api/memory/[id]` | የተወሰነ የማህደረ ትውስታ ግቤት ያግኙ |
| PUT | `/api/memory/[id]` | የማህደረ ትውስታ ግቤትን ያዘምኑ |
| DELETE | `/api/memory/[id]` | የማህደረ ትውስታ ግቤትን ይሰርዙ |
| GET | `/api/memory?q=` | ማህደረ ትውስታን ይፈልጉ (FTS5 + ቬክተር) — ስታቲስቲክስ በዚያው ምላሽ ውስጥ ተካትቷል |
**ማረጋገጫ፦** የአስተዳደር ክፍለ-ጊዜ ወይም በአስተዳደር ወሰን የተገደበ API ቁልፍ ያስፈልጋል።
---
## 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)ን ይመልከቱ።
---
---
## ማረጋገጫ
ስለ አራቱ የማረጋገጫ መረጃ ምድቦች (የዳሽቦርድ ክፍለ ጊዜ፣ የአካባቢያዊ CLI ቶከን፣ `oma_live_…` የመዳረሻ ቶከን፣ የአስተዳደር ወሰን ያለው API ቁልፍ) እና ከ inference ቁልፎች እንዴት እንደሚለዩ ለማወቅ [የአስተዳደር ማረጋገጫ](../guides/MANAGEMENT-AUTH.md)ን ይመልከቱ።
- የዳሽቦርድ መንገዶች (`/dashboard/*`) የ`auth_token` ኩኪን ይጠቀማሉ
- መግባት የተቀመጠውን የይለፍ ቃል hash ይጠቀማል፤ ካልተገኘ ወደ `INITIAL_PASSWORD` ይመለሳል
- `requireLogin` በ`/api/settings/require-login` በኩል ማብራትና ማጥፋት ይቻላል
- `REQUIRE_API_KEY=true` ሲሆን የ`/v1/*` መንገዶች እንደ አማራጭ Bearer API ቁልፍ ይጠይቃሉ
- በዚህ ማጣቀሻ ውስጥ "management token" / "management-scoped API key" ማለት በዚያ መመሪያ ውስጥ ካሉት ምድቦች አንዱን ነው — ያልተገለጸ ተጨማሪ የሚስጥር አይነትን አያመለክትም
> **ተኳኋኝነትን የሚያፈርስ ለውጥ (v3.8.0)** — `/api/v1/agents/tasks/*` እና የ cooldown አስተዳደር endpoints አሁን **የአስተዳደር ማረጋገጫ**ን (የዳሽቦርድ `auth_token` ኩኪ ወይም የአስተዳደር ወሰን ያለው API ቁልፍ) ይጠይቃሉ። ከዚህ ቀደም እነዚህን መንገዶች ያለማረጋገጫ የጠሩ ደንበኞች `401 Unauthorized` ይቀበላሉ። commit `588a0333` (`fix(auth): require management auth for agent and cooldown APIs`)ን ይመልከቱ።
Reference in New Issue View Git Blame Copy Permalink